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PREFACE 



This manual describes the Multics Report Writer which was developed from the LINUS 
report writer. The Multics Report Writer provides the capabilities to utilize formatted data 
extracted from sources other than Multics Relational Data Store data bases. The only user-visible 
change is the default page length which was changed from 66 to 0, resulting in unpaginated reports 
by default. 

This manual presupposes some basic knowledge of the Multics system, and does not attempt 
to provide information covered in either of the following two manuals: NEW USERS' 
INTRODUCTION TO MULTICS - PART I and PART II, Order No. CH24 and CH25 
respectively. 

This manual contains references to the MULTICS PROGRAMMER'S REFERENCE 
MANUAL (Order No. AG91) — referred to in this text as "Programmer's Reference Manual", 
the MULTICS SUBROUTINES and I/O MODULES (Order No. AG93) — referred to as 
"Subroutines Manual", and the MULTICS LOGICAL INQUIRY and UPDATE SYSTEM 
REFERENCE MANUAL (Order No. AZ49) — referred to as "LINUS Manual". 

The manual is divided into several sections which are outlined below. 

Sections 1 and 2 

contains overview and tutorial information which should be read by anyone intending to 
use the Report Writer directly, to produce formatted reports. 

Section 3 

contains overview and tutorial information on the subroutine interface to the Report 
Writer. This section should be read by anyone who intends to write a Multics subsystem 
that includes the Report Writer. 

Section 4 

contains descriptions of Report Writer requests. This section should be read by anyone 
intending to use the Report Writer. 

Section 5 

contains descriptions of Report Writer subroutine entrypoints. 
Section 6 

contains descriptions of Table Manager subroutine entrypoints. 
Section 7 

contains a PL /I example that uses the subroutine interface to the Report Writer. 
Sections 5 and 6 should be read by anyone who intends to write subsystems that include 
the Report Writer. 



The information and specifications in this document are subject to change without notice. 
This document contains information about Honeywell products or services that may not 
be available outside the United States. Consult your Honeywell Marketing Representative. 
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SECTION 1 



REPORT WRITER SYSTEM 



The Mul tics Report Writer (MRW) system is a generalized report writing facility that is 
included in a number of application subsystems. Utilizing this facility a user can: 

1. create formatted reports 

2. change and examine report layouts 

3. save report layouts 

4. restore report layouts 

The MRW provides an end-user-oriented subsystem request interface, and a programmer 
subroutine interface. Facilities are provided for application subsystems to use the 
terminal-oriented end-user interface to control the report writing process entirely from a 
program, or to use a combination of the two interfaces. 



SYSTEM OVERVIEW 

The MRW produces formatted reports from data that is viewed as a table. Through this 
facility the user can control: 

• page width and length 

• page breaks 

• page, group, and row headers/ footers 

• counts, subcounts, totals, and subtotals 

• hyphenation of overlength values 

• reordering and excluding selected columns 

• duplicate suppression 

• column alignment, editing, folding, separators, titles, and widths 

• sorting on one or more columns 

• directing the report to the terminal, a file, or an io switch 

• horizontal and vertical scrolling through the report 

The MRW is designed to serve the needs of the casual and experienced user. A casual user can 
have a default report layout provided by the system, while an experienced user can precisely 

define the report layout. 
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Basic Operation 

The MRW retrieves rows of information from a table and produces a formatted output 
report. The rows retrieved are specified through a mechanism provided by the subsystem which 
uses the report writer (e.g., in the LINUS subsystem, the input_query and translate_query 
requests are used to select the table of interest). 



Formatting Options 

A formatted report is produced under the control of "formatting options." Formatting 
options consist of a name (for identity) and a set value. An example of a formatting option is: 

-page_width 80 

where -page_width is the name of this option and "80" is the set value associated with the name. 
Formatting options which deal with columns require an "option identifier" to uniquely identify 
the column. For example, to set the width of a column, an identifier is needed to determine which 
column the width is to be set for. Identifiers can be given as the number of the column in the 
query, the name of the column, or a star name which is matched against the column names. 
Examples of formatting options with identifiers are: 

-width salary 10 
-folding 3 f i 1 1 
-alignment ** center 

The formatting options are grouped into the following classifications: 

general report options 

control the overall characteristics of a report. They are assigned default values when the 
application subsystem is first invoked, but can be changed by the user at any time. These 
values are retained for the entire session. General report options consist of: 

-del imi ter 

-f ormat_document_control s 
-hyphenat i on 
-page_f ooter_va 1 ue 
-page_header_va 1 ue 
-page_l ength 
-page_wi dth 
- 1 i 1 1 e_l i ne 
-truncat i on 

general column options 

control the overall characteristics of the columns, such as examining the value of certain 
columns to determine if a page break is to be generated. They are assigned default values 
for every new query, but can be changed by the user at any time. These values are 
retained only during the current query (i.e., until the next new query is generated). 
General column options consist of: 

-col umn_order 
-count 
-excl ude 
-group 

-group_f ooter_tr i gger 
-group_f ooter_va 1 ue 
-group_header_tr i gger 
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-group_header_va 1 ue 

=out ] i ne 

-page_break 

— r ow f ootc r_va ! us 

-row_header_va1 ue 

-subcount 

-subtotal 

-total 

specific column options 

control the characteristics of one specific column. They are assigned default values for 
every new query, but can be changed by the user at any time. These values are also 
retained only during the current query (i.e., until the next new query). These formatting 
options require an identifier to determine which column the particular option applies to. 
Specific column options consist of: 

-al i gnment 
-ed i t i ng 
-f ol d i ng 
-separator 
-title 
-width 

The values of formatting options are listed and set through the list_format_options and 
set_format_options requests. These requests take control arguments which are the names of the 
formatting options. For example, to determine the current page width, enter: 

1 i st_f ormat_opt i ons -page_width 
and to change page width, enter: 

set_f ormat_opt i ons -page_width 71 

A concept of "active" options is employed to make the system easier to use and to provide 
flexibility. For example, if a novice user does not set page headers, then no reference is made to 
them. If a user defines a page header, it then becomes active and appears in the output of the 
various reporting requests. If a user decides to eliminate a previously set page header, that is, by 
invoking the "set_format_options -page_header_vaiue -default", it reverts back to the 
"inactive" state. This concept reduces the number of options listed when the user invokes the 
list_format_options request with no control arguments. The page_header_value is not listed if 
set to its default value as previously described. 

Specific column options are active at all times, whereas general column options and general 
report options are active only when their value is set different from the original default value. 
For example, if the page_width is assigned its default value by the system, or is reverted to by the 
user, it is not active. The moment that it is changed to a value different from its default, it is 
considered active. 



Requests 

A number of requests are available for use in the creation of reports. Following is a brief 
summary of the report requests (refer to Section 4 for a detailed discussion of all requests): 

column_value 

returns the value of the specified column for the current row, previous row, or the next 
row. 
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display 

retrieves selected data, creates a report, and displays the information or writes it to a file 
or an io switch. 

display_builtins 

returns the current values for requested built-ins. 

list_f ormat_options 

displays the names and values of formatting options. 

restore_f ormat_options 

restores saved report layouts. 

save_f ormat_options 

saves current values of formatting options for future use. 

set_f ormat_options 

changes/sets report formatting options. 



DEFAULT REPORT ELEMENTS 



Page Layout and Titles 

A page consists of a title line followed by as many rows as fit on the remainder of the page. 
The default title line is made up of one or more column titles, one column title for each column on 
the page. The column title is the column name as selected through the application subsystem. The 
row is made up of one or more columns, all concatenated together to form the row. The page 
width is 79 character positions and the page length is 66 lines, with 3 of these lines, at the top and 
bottom, reserved for margins. 



Separators 

A separator is provided f or each column value and each column title. The default separator is 
two blanks placed between each pair of column titles and column values. The last column title or 
column value of a row has no separator. 



Folding and Width 

If when formatting a report, report elements do not fit within the defined width, "folding" 
takes place. Folding can occur in two different ways: "truncation" and "filling". Truncation 
means that the value is truncated to the defined width and the last displayable character is 
replaced by the truncation character(s) (normally "*"). Filling means that portions of the value 
are moved down to the next line(s), allowing the newly formatted value to appear within its 
defined width. The format_document_ subroutine (described in the Subroutines Manual) is used 
to provide filling of overlength values, and format document controls can optionally be supplied 
to provide greater control over the filling action. Filling takes place when a value is wider than its 
display width; when the value contains vertical tabs characters, horizontal tab characters, 
backspace characters, or newline characters; or when the alignment mode is set to "both". When 
column values do not have editing requests associated with them, the value is trimmed first (i.e., 
before the test for filling is done). Character and bit data types have trailing blanks trimmed, and 
all other data types have leading and trailing blanks trimmed. 



1-4 



GB63 



The default width for a column value is derived from the columns selected through the 
application subsystem. The width chosen is the exact number of characters needed to contain the 
value after it is converted from the subsystems internal data type, to character format, via PL/ 1 
conversion rules. When the default width is used, the column value always fits, but this width can 
be reduced by the user. The reduction of the column width can cause folding to occur. Column 
folding can be set to "fill" or "truncate" and proceeds as described above. The default for column 
values is "fill." 

The concatenation of all column values and separators (used to determine row value) can 
cause row folding to occur. This happens when the resulting row is wider than the defined page 
width. In this case, columns which appear on or to the right of the right page boundary are moved 
down to the next line(s). The corresponding titles are moved so that they appear directly over the 
columns. Columns whose widths are greater than the page width are automatically reduced to the 
page width. 



Alignment 

The alignment for column values is derived from the data type of the column, as defined by 
the application subsystem that uses the MRW. Character and bit strings default to 
"left-alignment," decimal data with a non-zero scale defaults to "decimal-point-alignment," and 
all other data types default to "right-alignment" The user can set the alignment of individual 
columns to left, right, center, both, or decimal-point-alignment. 

The alignment for a column title is center (i.e., the title is centered within its defined width). 

The alignment f or a title line or a row is lef t (i.e., the title line or row is placed against the lef t 
page boundary). 



OPTIONAL REPORT ELEMENTS 

A number of optional features (for greater control over report appearance) are available for 
more sophisticated report formatting. These optional features are: 

• editing 

• headers/ footers 

• column titles 

• active requests 

• page breaks 

• excluding columns 

• ordering of columns 

• grouping 

• outlining 

• totals and subtotals 

• counts and subcounts 
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• separators and delimiters 

• embedded control lines and hyphenation 



Editing 

Editing can be specified for any column value, and is provided by subsystem active requests 
and Multics active functions. The report column_value request is used to pass the value to other 
active requests, and the returned value is then f olded and aligned as described above (see "Folding 
and Alignment"). The MRW does not strip a level of quotes from the editing request; the first 
time quote-stripping occurs is when ssu_$evaluate_active_string subsystem utilities procedure is 
invoked. Editing of column values is not provided by default. 



Headers/Footers 

A header or footer is a character string provided by the user. The character string can 
contain active requests, be made up of more than one "portion," and consist of more than one 
line. A delimiter character is used to separate the different portions of a header or footer. The 
delimiter character default is "!", but can be changed by the user. The header/footer can consist 
of a left, right, and center page portion. 

Evaluation of a header /footer is a two-part operation that proceeds in the following 
manner: first, the header /footer is divided into its portions based on the delimiter character; and 
second, active requests are evaluated. Quote-stripping is not done by the MRW during these two 
operations; the first time quote-stripping occurs is when the ssu_$evaluate_active_string 
subsystem utilities procedure is invoked. The MRW display _builtins active request can be used to 
obtain built-ins like the current page number in a header /footer, and the MRW column_value 
active request can be used to obtain the value of a column. 

A header or footer can be made up of a left, right, and center page portion. These portions 
are determined by the delimiter characters. The portions are aligned to the lef t, right, and center 
of the page. Folding on headers/ footers proceeds independently for each part. Portions of a 
header or footer (left, right, or center) with zero length are redistributed to other portions whose 
lengths are not zero. For example, if the page header contained only a center portion as: 

! {Sample Center Portion!! 

the text would be centered on the page, but would have the full page width available for the text. 
Similarly, a lef t portion or right portion only is aligned to the lef t or right of the page, but has the 
full page width available for placement of its text. Two exceptions to this action are when the 
header or footer has a left, right, and center portion, and the left or right portion has a zero 
length. For example: 

Meft part!center part!! 

or 

Mcenter partlright part! 

In both cases the lef t or right part of the page is unavailable for placement of text (i.e., the space is 
not redistributed to the other two portions). 

If redistribution of the available page width is not desired, the placement of a single blank 
into a portion prevents the redistribution from taking place because the portion has a length 
greater than zero. For example: 
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S ! Center Part! ! 



Headers and footers can be defined for a page, group, and a row. The first row that appears 
on the page is available for the page header, and the last row that, appears on the page is available 
f or the page f ooter . The f irst row of a group is available f or the group header, and the last row of 
a group is available for the group footer. The current row is available for use in the row header 
and row footer. 



Column Titles 

A column title is a character string that is placed above its associated column. The display 
width available for the title is inherited from its parent column, along with the folding action. If 
the title is exactly the same number of characters as the display width, it is placed without any 
folding or alignment action. If the title is shorter, it is centered within the display width. If the 
title is wider, it is truncated or filled, depending on its parent column's setting. 



Active Requests 

Active requests are used in headers /footers to substitute values into the header /footer at the 
time the report is being formatted. For example, the Multics date active function can be used to 
provide the current date as part of the header or footer. 

Active requests are also used to provide editing for column values which become part of the 
row value. For example, the subsystem execute request and the Multics picture active function 
can be used to provide editing features such as dollar signs and commas. 

The user specifies subsystem active requests through the construct " [name STR]", where 
name is the name of the desired active request and STR is any argument(s) required by the active 
request. Multics active functions are invoked via the subsystems [execute] active request. They 
are specified by the user through the construct [execute name STR] , where name is the name of 
the Multics active function and STR is any argument(s) required by the active function. The 
active function /request is evaluated and its returned value is substituted into the original string 
before folding and alignment take place. 



Page Breaks 

Page breaks can be set to occur when the value of one or more columns change. The 
occurrence of a new value in the column(s) being examined closes out the current page and a new 
page is started. The new row which caused the page break is not made available until the start of 
the next page. This allows the page footer to access the correct row (the last row on that page). 



Excluding Columns 

Columns selected through the subsystem can be excluded from the row value. Through use of 
the [column_value] active request, the column value can be obtained for placement elsewhere on 
the page. For example, a user may exclude the display of a column that is being used to determine 
when to generate page breaks, and place the value of the column in the page header with the 
column_value active request. 
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Ordering of Columns 

Columns appear on the page in the order they were selected through the subsystem. This 
order can be changed by the user without having to go back and select a different order through 
the subsystem. 



Grouping 

One or more columns can be used to define a "group" of rows based on the values of these 
columns. The named columns make up a major to minor hierarchy and can be used in conjunction 
with the outlining, page break, subtotal, and subcount features. 



Outlining 

One or more columns can have duplicate values suppressed. If the value of the current 
column is the same as the previous value, then its display is suppressed unless it is the first line on a 
new page. 

If any named column is a member of the group of columns defined via the grouping feature, 
it and any columns more major in the hierarchy are outlined. A change in value of any one 
column displays all values of columns lower in the hierarchy in addition to the changed column. 
An exception is the first line on a new page, when duplicate values are never suppressed. 



Totals and Subtotals 

Totals and subtotals can be specified for columns. The totals and subtotals are placed directly 
under the associated columns. 

A column subtotal is generated when the value of the column(s) the subtotal is associated with 
changes. The subtotal can be associated with one or more columns. Several subtotals can be 
specified, each associated with different columns. Subtotals can be "reset" or "running." A 
column total is generated after the last input row is processed. 

The width, alignment, folding, and editing request for a total or subtotal is inherited from its 
parent column. During the generation of a total or subtotal, the column_value request returns the 
value of the total or subtotal, rather than the column value. When the parent column is excluded 
from the page, the total or subtotal associated with it is also excluded. An exception to this rule is 
when all of the columns have been excluded. They are provided in this case to produce reports 
containing some combination of subcounts, subtotals, counts, and totals only. 



Counts and Subcounts 

Counts and subcounts can be specified for columns, and function as described above under 
"Totals and Subtotals." A count or subcount counts occurrences of values, whereas a total or 
subtotal accumulates values. 



Separators and Delimiters 

The separators used to separate column values and column titles from each other can be set 
to any string of displayable characters by the user. The delimiter character used to delimit the 
different portions of a header /footer can also be set by the user. 
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Embedded Control Lines and Hyphenation 

The MRW uses the format_document_ subroutine (refer to the Subroutines Manual) to 
"fill" over length text. A user can embed format document control lines in text to achieve greater 
control of the filling action. A user can also specify that hyphenation of words should be 
attempted when filling overlength text. 



FULL PAGE FORMATTING 

The MRW system formats a full page before any output is provided. It operates in this 
fashion because it is sometimes necessary to back up on a page and defer report elements to the 
next page so that associated report elements remain on the same page. A full page with all report 
elements present is outlined in the following diagram. 



Formatted Page 



PAGE HEADER 



TITLE BLOCK 



DETAIL BLOCK 1 



expanded in diagram below 



DETAIL BLOCK_N 
PAGE FOOTER 



Detail Block 



GROUP HEADER 
ROW HEADER 
ROW VALUE 
SUBTOTAL BLOCK 
SUBCOUNT BLOCK 
TOTAL BLOCK 
COUNT BLOCK 
ROW FOOTER 
GROUP FOOTER 
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All of the defined report elements are optional, but at least one must be present or a 
zero-length page results. A zero-length page is treated as an error and the report formatting is 
terminated. 

Backing up on a page is accomplished through a detection and prevention method, and 
proceeds as follows: 

1. The page header, if present, is processed first. If the page header does not fit on the 
page, it is treated as an error and the report formatting is terminated. The formatted 
page header can fill the complete page if no other report elements are defined. 

2. The title line, if present, is processed next. If the title line does not fit on the page, it is 
treated as an error and the report formatting is terminated. The formatted title block 
can fill the complete page if no other report elements are defined. 

3. The detail block is processed next. A detail block can be made up of a group header, a 
row header, a row value, a subtotal block, a subcount block, a total block, a count block, 
a row footer, and a group footer. These different elements are treated as one unit and 
must all appear on one page or the detail block is deferred to the next page. If any of 
these elements are defined, then at least one detail block must fit on the page or it is 
treated as an error and the report formatting is terminated. The formatted detail block 
can fill the complete page if no other report elements are defined. 

a. The group header, if present, is processed first. If the current row is the first row of 
the report, or if the column associated with the -group_header_trigger option has 
just changed with the current row, the header is generated. If the group header does 
not fit on the page, the detail block is deferred to the next page, provided one detail 
block is already placed on the page. 

b. The row header, if present, is processed next. If the row header does not fit on the 
page, the detail block is deferred to the next page, provided one detail block is 
already placed on the page. 

c. The row value, if present, is processed next If the row value does not fit on the 
page, the detail block is deferred to the next page, provided one detail block is 
already placed on the page. The editing requests associated with any columns are 
evaluated before an attempt is made to place the row value on the page. If the row 
value is deferred to the next page for any reason, the editing requests associated with 
the columns are evaluated again when the row value is processed on the next page. 
This is necessary to ensure that obtained values, such as the page_number display 
built-in are correct. For users who are doing calculations based on accumulations, 
this could produce incorrect calculations. That is, the value of a row could be 
accumulated more than once. The previously_processed_row display built-in 
provides a mechanism to ensure this does not happen. If the value of this built-in is 
true, a user doing accumulations would not add in the current row value as it was 
already added in when the editing requests for the row were processed the first time. 

d. The row subtotal, if present, is processed next. If subtotal generation is necessary, 
and the row subtotal does not fit on the page, the detail block is deferred to the next 
page, provided one detail block is already placed on the page. The editing requests 
associated with any subtotals are only evaluated when subtotal generation is done, 
and proceed as described above under "row value" editing requests evaluation. The 
previously_processed_row display built-in also functions as described above. 
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e. The row subcount, if present, is processed next It proceeds as described above 
under row subtotal (item d). 

f . The row total, if present, is processed next If total generation is necessary, and the 
row total does not fit on the page, the detail block is deferred to the next page, 
provided one detail block is already placed on the page. The editing requests 
associated with any totals are only evaluated when total generation is done, and 
proceed as described above under "row value" editing requests evaluation. The 
previously_processed_row display built-in also functions as described above. 

g. The row count, if present, is processed next. It proceeds as described above under 
row subtotal (item d). 

h. The row footer, if present, is processed next. If the row footer does not fit on the 
page, the detail block is deferred to the next page, provided one detail block is 
already placed on the page. 

i. The group footer, if present, is processed last If the current row is the last row of 
the report, or the column associated with the -group_footer_trigger option is about 
to change with the next row, the footer is generated. If the group footer does not fit 
on the page, the detail block is deferred to the next page, provided one detail block 
is already placed on the page. 

The page footer, if present, is processed last If the page footer does not fit on the page, 
the last detail block on the page is removed and the page footer is processed again. 
Active requests found in the footer are evaluated again to ensure correct processing of 
display built-ins like current_row_number. If the page footer still does not fit, another 
detail block is removed from the page and the footer is evaluated again. This process 
continues until the footer fits, or there are no more detail blocks to remove from the 
page. The first detail block that appears on the page is never removed, and if its removal 
is necessary to provide a fit for the page footer, it is treated as an error and report 
formatting is terminated. 
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SECTION 2 



REPORT WRITER TUTORIAL 



This section consists of report writer examples organized into a sample user session. An 
application subsystem called "display _employee" was constructed for these examples, and a 
complete listing of it can be found in Section 6. User-typed lines and lines displayed by the 
system are shown together in the example. To differentiate between these lines, an exclamation 
mark (!) precedes user-typed text. This is done only to distinquish user text from 
system-generated text; it is not to be included as part of the input line. Also, a "carriage return" 
(moving the display mechanism to the first column of the next line, called a newline or NL on 
Multics) is implied at the end of every user-typed line. Line numbers are also included in the 
examples for purposes of commentary immediately following the example. 

Note: Because of page constraints in this document, certain character strings of data used 
in examples may not match exactly the information as seen on a user's terminal. 
That is, the character strings in examples may be folded or multiple-lined, whereas 
the actual interactive (live) session may display the same information on a single line 
or multiple lines with different line breaks than shown here. Additionally, some 
blank lines have been removed in the examples for space consideration. In most 
cases this can be recognized by the reader. For example: 



55 ! d i spl ay_empl oyee: display -page 1 

59 (system display) 

Only one space is used to separate the lines, but the line numbers to the left of the 
lines imply there are actually three spaces here. 

In other cases, lines have purposely been skipped or eliminateo ecause of changes 
made while developing the examples. 



Following is a list of request and control argument abbreviations used in the tutorial 
examples. They are included here for the purpose of saving the reader from referring to other 
sections of the manual if a term is unfamiliar. The list includes only those abbreviations used 
within this section. 



REQUEST ABBREVIATIONS 




col umn_va 1 ue 

display 

display_bui 1 tins 
execute 



dib 



e 



ec 
Is 



exec_com 

list (Multics command level) 
1 i st_f ormat_opt i ons 
print (Multics command level) 
qui t 

restore_f ormat_opt ions 



Isfo 



q 



rsf o 
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This page intentionally left blank. 
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sfo set_f ormat_opt i ons 

svfo save_f ormat_opt ions 

w wr i te 



CONTROL ARGUMENT ABBREVIATIONS 



-al 


-al i gnment 


-co 


-col umnjDrder 


-dm 


-del imi ter 


-ed 


-edi ti ng 


-ex 


-exc 1 ude 


-f dc 


-f ormat_document_control s 


-fold 


-f old i ng 


-gft 


-group_f ooter_tr i gger 


-gfv 


-group_f ooter_va 1 ue 


-ght 


-group_header_tr i gger 


-ghv 


-group_header_value 


-gr 


-group 


-hph 


-hyphenation 


-kr 


-keep_retr i eval 


-krp 


-keep_r epor t 


-nr 


-new_retr i eva 1 


-of 


-output_f i 1 e 


-or 


-ol d_retr i eva 1 


-orp 


-ol d_report 


-out 


-out 1 i ne 


-pb 


-page_break 


=,-..«» . 

pi V 


-page_f ooter_va 1 ue 


-pg 


-page 


-phv 


-page_header_va 1 ue 


-pi 


-page_l ength 


-pw 


-page_wi dth 


-rf v 


-row_f ooter_va 1 ue 


-rhv 


-row_header__va 1 ue 


-rs 


-reset 


-sep 


-separator 


-stt 


-subtotal 


-tc 


-truncat i on 


-td 


-temp_d i r 


-tl 


-ti tle_J ine 


-tt 


-total 


-ttl 


-title 


-w i d 


-width 



2-3 



GB63-00 



GENERAL REPORT OPTIONS-1 



1 ! di spl ay_empl oyee 

5 ! di spl ay_empl oyee : lsfo -dm -fdc -hph -pfv -phv -pi -pw -tl -tc 



-delimiter "!" 

-f ormat_document_contro1 s "off 

-hyphenation "off 

-page_f ooter_va 1 ue " " 

-page_header_va 1 ue " " 

-page_ length "0" 

-page_width "79" 

-t i 1 1 e_l i ne "on" 

-truncation "*" 



7 ! di spl ay_empl oyee : sfo -pw 0 

8 ! di spl ay_empl oyee : lsfo -pw 

-page_width 



9 ! di spl ay_empl oyee : sfo -pw -default 

10 ! di spl ay_empl oyee : lsfo -pw 

-page_width :: 7a :: 
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line 1 

Invoke display _employee. 

line 5 

List the names and values of specified report formatting options. All of the 
displayed values in this case are "default" values. These options are the "general 
report options." They remain in effect across the entire subsystem session. For 
example, if the page width is changed, it remains at this new value until it is explicitly 
changed back, or until the subsystem session is terminated. 

-dm "!" character used to delimit portions of header /footer. 

-fdc "off" used when filling overlength character strings. If "off," 

ignore embedded controls. 

-hyphenation "off" used when filling overlength character strings. If "off," do 

not attempt to hyphenate words. 

-pfv "" footer placed at bottom of each page. 

-phv "" header placed at top of each page. 

-pi "0" length of each formatted page (number of lines). 

-pw "79" width of each formatted page (number of character positions). 

-tl "on" print the title line. 

-tc "*" character that indicates truncation has occurred, 
lines 7-10 

Set page width, list page width, reset page width, and list page width once again. 
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SPECIFIC COLUMN OPTIONS 



The following example looks at "specific column options." These options are always listed 
and are assigned new default values each time a new set of columns are selected. 



1 ! di spl ay_empl oyee : 
6 -al ignment age 
-al ignment ci ty 
-alignment family 
-al ignment job 
-al ignment name 
-alignment salary 
-al ignment sex 
-al ignment state 



lsfo 



14 



22 



30 



38 



46 



-editing age 
-editing city 
-editing family 
-editing job 
-editing name 
-editing salary 
-editing sex 
-editing state 
-folding age 
-folding city 
-folding family 
-folding job 
-folding name 
-folding salary 
-folding sex 
-folding state 
-separator age 
-separator city 
-separator family 
-separator job 
-separator name 
-separator salary 
-separator sex 
-separator state 



"right" 
" 1 ef t " 
" 1 ef t " 
" r i ght " 
"left" 
"decimal 8" 
"left" 
"left" 



"fill 
"fill 
"fill 
"fill 
"fill 
"fill 
"fill 
"fill 



-t 


tie 


age 


"age " 


-t 1 


tie 


ci ty 


"ci ty " 


-tl 


tie 


f ami 1 y 


"f ami ly" 


-t 1 


tie 


j ob 


"job " 


-tl 


tie 


name 


"name" 


-f 


tie 


sal ary 


"salary" 


-t ■ 


tie 


sex 


"sex" 


-f 


tie 


state 


"state" 


-w 


dth 


age 


"5" 


-w 


dth 


ci ty 


"13" 


-w 


dth 


f ami 1 y 


" 1 " 


-w 


dth 


job 


"5" 


-w 


dth 


name 


" 10" 


-w 


dth 


sal ary 


" 10" 
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-width sex 
53 = width stats 



" 1" 



line 1 

List the names and values of the column options, 
lines 6-13 

System display — the alignment option specifies how a value is to be aligned within 
its display width. 

• Character and bit strings default, to left-alignment. 

• Decimal data with a non-zero scale defaults to 
decimal-point-alignment 

• All other data types default to right-alignment. 

lines 14-21 

System display — the editing option provides additional editing for column values. 
(Default is no editing) 

lines 22-29 

System display — the folding option specifies the action taken when the column 
value exceeds the display width for the column. (Default is fill) 

lines 30-37 

System display — the separator option specifies the character string that separates 
the specified column from the following col umn. auit is iwc uianKSy 

lines 38-45 

System display — the title option specifies the character string to be placed at the 
top of the page above the column. (Default is the column name) 

lines 46-53 

System display — the width option specifies the display width of the detail line of 
the column. (Default is the number of characters needed after conversion to 
character format) 
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The following examples look at a report utilizing the available specific column options. 



55 ! 


1 display_ 


empl oyee : 


sfo -pi 66; 


di -pg 1 








59 


name 


j ob 


sal ary 


age s 


f 


St 


c 1 ty 










e 


a 


at 












X 


m 


e 





i 
1 

y 



66 


abel 


1 


14555. 


01 


36 


m 


s 


ak 


juneau 


67 


abel 1 


2 


1 3000 . 


01 


55 


f 


m 


az 


phoeni x 


68 


abernathy 


3 


12500. 


.01 


61 


m 


d 


ca 


f resno 


69 


abodoura 


5 


12900. 


.01 


61 


m 


m 


ca 


sacramento 


70 


aboe 


4 


10201 . 


.01 


41 


f 


s 


ca 


los angel es 


71 


abraham 


6 


15000 


.01 


25 


f 


d 


ca 


san diego 


72 


abrahms 


7 


14300 


.01 


35 


m 


s 


ca 


san francisco 




. (45 data 


1 i nes ) 
















118 


baker 


1 


12000 


. 10 


71 


m 


s 


i 1 


springf ield 



line 55 

Set page length to 66 and display page 1. Data is retrieved and formatted by default 
parameters. 

Note: Multiple report writer requests can be included in a single request line 
by utilizing the request termination character (;) between requests. 
Any number of requests may be included on a line using this format, 

lines 59-118 

System display 
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120 ! di spl ay_emp1 oyee : 1 sfo -wid state 
-width state "2" 



123 ! di spl ay_empl oyee : sfo -wid state 5 
125 ! di spl ay_empl oyee : di -pg 1 



129 


name 


job 


sal ary 


age 


s 


f 


state 


ci ty 














e 


a 


















X 


m 
i 




















1 

y 






136 


abel 


1 


14555 . 


01 


36 


m 


s 


ak 


juneau 


137 


abel 1 


2 


1 3000 . 


01 


55 


f 


m 


az 


phoeni x 


138 


abernathy 


3 


12500. 


01 


61 


m 


d 


ca 


f resno 


139 


abodoura 


5 


1 2900 . 


01 


61 


m 


m 


ca 


Sacramento 


140 


aboe 


4 


10201 . 


01 


41 


f 


s 


ca 


los angel es 


141 


abraham 


6 


1 5000 . 


01 


25 


f 


d 


ca 


san diego 


142 


abrahms 


7 


14300. 


01 


35 


m 


s 


ca 


san francisco 




. (45 data 


1 i nes ) 
















188 


baker 


1 


12000. 


10 


71 


m 


s 


i 1 


spr ingf ield 



line 120 

List the width value of the "state" column, 
lines 123-125 

Set the width value for state column to "5" from its default value of "2", and display 
page 1. 

lines 129-188 

System display — note the difference in the state column header on line 129 from 
that displayed on lines 59-61. 
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190 ! di spl ay_empl oyee : lsfo -wid 8 

-width city "13" 



193 ! di spl ay_empl oyee : sfo -wid 8 10 
195 ! di spl ay_empl oyee : di -pg 1 

199 name job salary age s f state city 

e a 
x m 
i 
1 

y 



206 


abel 


1 


14555. 


01 


36 


m 


s 


ak 


juneau 


207 


abel 1 


2 


13000. 


01 


55 


f 


m 


az 


phoeni x 


208 


abernathy 


3 


12500. 


01 


61 


m 


d 


ca 


f resno 


209 


abodoura 


5 


12900. 


01 


61 


m 


m 


ca 


sacramento 


210 


aboe 


4 


10201 . 


.01 


41 


f 


s 


ca 


1 OS 


211 


















angel es 


212 


abraham 


6 


15000. 


.01 


25 


f 


d 


ca 


san diego 


213 


abrahms 


7 


14300 


.01 


35 


m 


s 


ca 


san 


214 






















(37 data 


1 i nes ) 
















252 


arnol d 


22 


18210 


.01 


53 


f 


d 


pa 


phi 1 adel ph 


253 


















i a 


254 


ashman 


23 


12400 


.01 


52 


m 


s 


tn 


chattanoog 


255 


















a 


256 


ashworth 


24 


9301 


.01 


61 


f 


m 


tx 


aust i n 


257 


asi n 


1 


15100 


.01 


51 


m 


d 


tx 


da 1 1 as 


258 


auburn 


2 


13101 


.01 


70 


f 


s 


vt 


rutl and 



line 190 

List the width value of column 8 (city) 



lines 193-195 

Set the width value of the 8th column to "10" from its default value of "13", and 
display page 1. 



lines 199-258 

System display — note the difference under the city header (lines 210-214) from 
that displayed on lines 140-142. Also notice the not-so-pleasant breakup of lines 
252-255. This is an example of column "filling." 
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260 ! di spl ay_emp1 oyee : 
-width name 



sfo -wid 8 -def aul t ; 1 sf o -wid name 
"10" 



263 ! display_emplcyee: sfo -wid name 7 -fold name truncate 
265 ! di spl ay_empl oyee : di -pg 1 

269 name job salary age s f state city 

e a 

x m 
i 
1 

y 



277 


abel 1 


2 


1 3000 . 


,01 


55 


f 


m 


az 


phoeni x 


278 


aberna* 


3 


12500. 


.01 


61 


m 


d 


ca 


f resno 


279 


abodou* 


5 


12900 


.01 


61 


m 


m 


ca 


sacramento 


280 


aboe 


4 


10201 . 


.01 


41 


f 


s 


ca 


los angel es 




(47 data 


1 i nes ) 
















328 


baker 


1 


12000 


. 10 


71 


m 


s 


i 1 


spr ingf iel d 



line 260 

Set the width value of column 8 (city) to its default value (13) and list the width value 
of the name column. 

lines 263-265 

Set the width value of the name column to "7", truncate the data listed under the 
name column, and display page 1. 

lines 269-279 

System display — note the difference under name header (lines 278-279) from that 
displayed on lines 208-209. 
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330 


sfo -sep 
















332 


di spl ay_ 


empl oyee : 


di -pg 1 












336 


nam© 




sa 1 ary j 


oyc 




f 


s tat© 


city 












£ 


a 


















m 


















1 

y 






343 


abel 


1 1 I 


14555.01 | 


36 


m 


s 


ak 


juneau 


344 


abel 1 


I 2 j 


13000.01 j 


55 


f 


m 


az 


phoeni x 


345 


aberna* 


I 3 | 


12500.01 j 


61 


m 


d 


ca 


f resno 


346 


abodou* 


I 5 | 


12900.01 | 


61 


m 


m 


ca 


sacramento 


347 


aboe 


I 4 I 


10201.01 | 


41 


f 


s 


ca 


los angel es 



(47 data lines) 



395 baker | 1 j 12000.10 | 71 | m | s | il | Springfield 



lines 330-332 

Set the column separator value to "<SP> | <SP>" from its default value of <SP><SP> 
(two blanks), and display page 1. 

lines 336-395 

System display — note that the columns have shifted to the right because the 
separator was increased to three character positions. Previous example separators 
were only two character positions. 
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397 ! display_employee: sfo -al age left -ed salary -prompt 

338 Enter -editing salary. 

399 ! [e pic $zz,zz9v.99 [civ salary]] 

400 ! . 



402 


di spl ay_ 


empl oyee : 


di -pg 1 












406 


name 


1 J ob 1 


sal ary 


age 


I s 


f 


state 


ci ty 












I e 


a 
















| X 


m 
i 


















1 

y 






413 


abel 


1 1 I 


$14,555.01 


| 36 


I m 


s 


ak 


j uneau 




abel 1 


I 2 | 


$13,000.01 


55 


| f 


m 


az 


phoeni x 




aberna* 


I 3 ; 


$12,500.01 


61 


I m 




ca 


f resno 




abodou* 


I 5 I 


$12,900.01 


61 


I m 


ID 


ca 


sacramento 



( 48 data 1 i nes ) 



464 baker | 1 | $12,000.10 | 71 | m | s | il | Springfield 



line 397 

Set alignment value for age column to "left" from its default value of "right," and 
invoke the editing option with prompt. 

lines 399-402 

Edit request, termination, and display page 1. 

lines 406-464 

System display — note that the information under the age column is now aligned to 
the left of the column and the data under the salary column contains the "$" and "," 
characters. 
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466 ! di spl ay_empl oyee : 

-title age 

-title ci ty 

-title fami ly 

-title job 

-title name 

-title salary 

-title sex 

-title state 



lsfo -ttl ** 

"age " 
"city" 
"fami ly" 
« j ob " 
" name " 
"sal ary" 
"sex" 
"state" 



476 ! 
477 

478 ! 

479 ! 
480 

481 ! 

482 ! 
483 

484 ! 

485 ! 
486 

487 ! 

488 ! 
489 

490 ! 

491 ! 
492 

493 ! 

494 ! 
495 

496 ! 

497 ! 
498 

499 ! 

500 ! 



display_employee: sfo -al age -default;sfo -ttl (1 2 3 4 5 6 7 8) -prompt 

Enter -title name. 

NAME 

Enter -title job. 
JOB 

Enter -title salary. 
SALARY 

Enter -title age. 
AGE 

Enter -title sex. 
SEX 

Enter -title family. 
FAMILY 

Enter -title state. 
STATE 

Enter -title city. 
CITY 



506 



di spl ay_ 


empl oyee : 


di -pg 1 










NAME 


| JOB | 


SALARY | 


AGE 


I s 


F 


STATE | 




1 1 






E 


A 






1 1 






X 


M 






1 1 








I 






1 1 








L 






1 1 








Y 




abel 


1 1 I 


$14,555.01 | 


36 


m 


s 


ak | 


abel 1 


I 2 | 


$13,000.01 | 


55 


f 


m 


az | 


aberna* 


I 3 | 


$12,500.01 j 


61 


m 


d 


ca | 



CITY 



j uneau 
phoenix 
f resno 



565 



(49 data 1 i nes ) 
baker j 1 J $12,000.10 



| 71 j m | s | il 



Springfield 
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line 466 

List the title values of all columns, 
lines 476=502 

Set the title value for all columns to new values (in this case, all have been changed 
from lowercase to uppercase), and display page 1. 

lines 506-565 

System display — note that the column header values on line 506 are different from 
that displayed on line 406. 
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GENERAL REPORT OPTIONS -2 



The following examples look at the "general report options" and are an extension to the 
example shown above under "General Report Options-1." 



1 ! di spl ay_empl oyee : 
3 ! d i sp 1 ay_emp 1 oyee : 



sfo -pi 26 
di -pg 1 



NAME | 


JOB | 


SALARY | 


AGE 


S 


F 


STATE 


CITY 










E 


A 














X 


M 
















I 
















L 
















Y 






abel I 


1 | 


$14,555.01 | 


36 


m 


S 


ak 


j uneau 


abell ] 


2 I 


$13, 000 .01 | 


55 


f 


m 


az 


phoeni x 


aberna* | 


3 I 


$12,500.01 j 


61 


m 


d 


ca 


f resno 


(9 data 


1 ines) 














agee | 


14 | 


$30,900.01 | 


70 


m 


s 


hi 


honolulu 



lines 1-3 

Set the page length value to "26" from its previously set value of "66" (see line 55 
above), and display page 1. 

lines 7-27 

System display — note that the report length has decreased. There are now 20 text 
lines and three "margin lines" at the top and at the bottom of the page. When the 
report is sent to a file (for later printing), these six margin lines are put in the report 
by the line printer sof tware. This produces the same page format, whether viewed at 
a terminal or on hardcopy. 
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29 ! di spl ay_emp1 oyee : sfo -phv -prompt 

30 Enter -page_header_va1 ue . 

31 ! ! [e date]!Samp1e Report! [e time]! 

32 i ! I ! I 

33 ! . 



35 ! di spl ay_emp1 oyee : di -pg 1 



39 04/29/83 



Sample Report 



10.26 



NAME | 


JOB 


SALARY | 


AGE 


S 


F 


STATE 


CITY 










E 


A 














X 


M 
















I 
















L 
















Y 






abel | 


1 


$14,555.01 | 


36 


m 


s 


ak 


j uneau 


abell | 


2 


$13,000.01 | 


55 


f 


m 


az 


phoeni x 


aberna* | 


3 


$12,500.01 | 


61 


m 


d . 


ca 


f resno 



( 7 data 1 i nes ) 
58 adkins | 11 j $20,700.01 



75 



f 1 



| key west 



line 29 

Set the page header value when prompted by the system. 

line 30 

System display — prompt 

lines 31-35 

Set page header to contents of lines 31-32 (two header lines), terminate, and display 
page 1. 

lines 39-58 

System display — note that a page header (line 39) is now included as part of the 
report This two-line page header reduces the page content of the report (i.e., the 
report now consists of 18 data lines whereas the previous example contained 20 
lines). The page header fills the entire page width, but the column values do not If 
the page width is set to zero, the display request calculates the page width to be an 
exact fit (i.e., contains all of the column values and separators). 
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60 ! di splay_emp1 oyee : 
62 ! d i sp 1 ay_emp 1 oyee : 

66 04/29/83 



sfo -pw 0 
di -pg 1 



Sample Report 



10:26 



NAME | 


JOB 


SALARY | 


AGE 


S 


F 


STATE 


CITY 










E 


A 














X 


M 










I 






I 
















L 










I 






Y 






abel 


1 


$14,555.01 | 


36 


m 


s 


ak 


j uneau 


abell | 


2 


$13,000.01 j 


55 


f 


m 


az 


phoeni x 


aberna* | 


3 


$12,500.01 j 


61 


m 


d 


ca 


f resno 



(7 data 1 ines) 
85 adkins | 11 I $20,700.01 



75 



f 1 



| key west 



lines 60-62 

Set the page width value to "0" from its default of "79," and display page 1. 
lines 66,85 

System display — note that the page header is now centered over the columns. 
Setting the page width to zero has one disadvantage: when set to some positive 
integer and a column width exceeds the page width, that column width is reduced to 
the page width. For example, if the page width is set to 80 and the width for a 
column is set. to 1024, the column width is reduced by the display request to 80. The 
reduction of a column display width does not take place when the page width is set to 
zero. 
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87 ! display_employee: sfo -pfv -prompt 

88 Enter -page_f ooter_va1 ue . 

89 ! ! ! ! ! 

90 ! !!- Page [dib page_number ] -!! 

91 ! . 



93 ! di spl ay_empl oyee : di -pg 1 



97 04/29/83 



Sample Report 



10:26 



1 14 



NAME | 


JOB 


SALARY | 


AGE 


S 


F 


STATE 


CITY 




1 






E 


A 














X 


M 

I 
L 

Y 






abel j 


1 


$14,555.01 | 


36 


m 


S 


ak 


juneau 


abell | 


2 


$13,000.01 j 


55 


f 


m 


az 


phoeni x 


aberna* | 


3 


$12,500.01 j 


61 


m 


d 


ca 


f resno 


abodou* | 


5 


$12,900.01 | 


61 


m 


m 


ca 


sacramento 


aboe | 


4 


$10,201.01 | 


41 


f 


s 


ca 


1 os angel es 


abraham | 


6 


$15,000.01 j 


25 


f 


d 


ca 


san diego 


abrahms j 


7 


$14,300.01 | 


35 


m 


s 


ca 


san f ranci sco 


acee | 


8 


$12,700.01 j 


34 


f 


m 


CO 


denver 


acord | 


9 


$10,500.01 | 


41 


m 


d 


ct 


| hartford 



1 16 



- Page 1 - 



line 87 

Set the page footer value when prompted by the system. 

line 88 

System display — prompt 

lines 89-93 

Set the page footer to contents of lines 89-90 (two footer lines), terminate, and 
display page 1. 

lines 97-116 

System display — note that a page footer (line 116) is now included as part of the 
report. This two-tine page footer reduces the page content of the report by another 
two lines (now 16 lines of data between header and footer). 
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di spl ay_ 


empl oyee : 


sfo -pi 66;di • 


-pg 


1 








04/29/83 




Sampl e 


Report 






10 


NAME 


| JOB | 


SALARY | AGE 


I s 


F 


STATE 


CITY 










| E 


A 














I x 


M 
















I 
















L 
















Y 






abel 


1 1 I 


$14,555.01 | 


36 


I m 


S 


ak 


j uneau 


abel 1 


I 2 j 


$13, 000 .01 | 


55 


| f 


m 


az 


phoen i x 


aberna* 


I 3 I 


$12,500.01 j 


61 


I m 


d 


ca 


f resno 



(45 data 1 i nes ) 
179 azer | 5 | $12,600.01 | 44 | m 

181 - Page 1 - 



norf ork 



line 118 

Set the page length to 66 lines from its previous setting of "26" (see line 1 of this 
example set). 

lines 122-181 

System display — note that the page now consists of 66 lines (3 blank margin lines at 
top and bottom and 60 lines of report). 
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183 I di spl ay_empl oyee : 



sfo -tc <MORE>;cii -pg 1 



187 04/29/83 Sample Report 10:26 



189 


NAME 


| JOB | 


SALARY J 


AGE | 


S 


I F 


STATE 


CITY 








1 




E 


I A 












i 




X 


i M 












1 






I I 












i 






i l 






194 






i 

! 






I Y 








abel 


1 1 I 


$14,555.01 j 


36 | 


m 


I S 


ak 


j uneau 




abel 1 


i 2 | 


$13,000.01 | 


55 i 


f 


I m 


az 


phoeni x 


198 


a<M0RE> 


! 3 | 


$12,500.01 | 


61 


m 


I a 


ca 


fresno 


199 


a<M0RE> 


I 5 j 


$12,900-01 j 


61 


m 


I n. 


ca 


sacramento 




aboe 


I 4 I 


$10,201.01 | 


41 | 


f 


I ■ 


ca 


los angel es 




(43 


data 1 i nes ) 












244 


azer 


1 5 1 


$12,600.01 | 


44 


m 


I s 


va 


| norfork 


246 








Page 1 





























line 183 

Set the truncation value to "<MORE>" from i-ts previous default value of "*," and 
display page 1= Refer to line 263 in the "Specific Column Options" example (above) 
where the width value of the name column was set to "7" and the folding option, with 
truncation (Default = *), was turned on for the name column. 

lines 187-246 

System display — note the different truncation of the name column values (lines 
198-199) from that displayed in the earlier example identified above (lines 278-279). 
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248 ! di spl ay_empl oyee : sfo -tl off;di -pg 3 

252 04/29/83 Sample Report 10:26 

254 c<M0RE> j 3 | $12,501.01 | 76 | m | m | ca | san francisco 

cummins | 4 | $10,100.01 | 78 | f ( d | co | denver 

cutchin | 5 | $12,600.01 | 62 | m | s | ct | hartford 

( 52 data 1 i nes ) 

309 , goodwyn | 15 | $12,400.01 | 39 | f | d | ct | hartford 

311 - Page 3 - 



313 ! di spl ay_empl oyee : sfo -tl on 



line 248 

Set the title line value to "off" from its previous default value of "on," and this time 
display page 3. Turning the title line off inhibits the column header or title display 
from that displayed in the previous example (lines 189-194). 

line 313 

Set the title line value to "on." This restores the display of column header or title 
lines. 
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Special Editing of a Report 

The following example shows how to utilize a user-defined exec_com and interact with the 
editing request. 



1 

3 
4 
5 
6 
7 
8 
9 
10 
1 1 
12 



di spl ay_empl oyee : sfo -wid sex 6 -ed sex "[ec sex_Jookup [civ sex]] 

d i sp 1 ay_emp 1 oyee : . . ted 

a 

&version 2 
&trace off 
&if &[e equal m &1 ] 
Sthen &return male 
&else &return female 
\f 

w sex_l ookup . di spl ay_empl oyee 

q 



14 ! display_employee: di -pg 1 
18 04/29/83 



Sample Report 



10:26 



20 



NAME 



27 
28 



abel 
abel 1 
a<M0RE> 



JOB 



SALARY 



1 | $14,555.01 

2 | $13,000.01 

3 | $12,500.01 



AGE 



(45 data 1 i nes ) 
75 azer | 5 | $12,600.01 | 

77 



36 
55 
61 



SEX 



ma 1 e 
f ema 1 e 
mal e 



44 | male 
Page 1 - 



| F 


STATE j 


I A 




I M 




| I 




| L 




I Y 




I 5 


ak 


I m 


az 


I ci 


ca 


! s 


va 



CITY 



j uneau 
phoeni x 
f resno 



| norfork 
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line 1 

Set the width of the sex column to "6" from its previous default value of "1," and 
prepare for special editing of the sex column data. 

lines 3-12 

Invoke the ted editor, append the following exec_com data (lines 5-9) into the ted 
buffer, terminate append mode, write the buffer to permanent storage, and quit the 
ted editor. 



line 14 

Display page 1. 



lines 18-77 

System display — note the change in width of the sex column (line 20) from that 
displayed in the previous example (line 189) and the change of data by the exec_com 
(m = male and f = female). 
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Saving a Report and Resetting Options 

The following example shows how to save a report after it is in the desired format. 
Additionally, the example shows how to reset all options and revert the report back to its original 
format. 



1 ! di spl ay_empl oyee : 

2 ! displ ay_empl oyee : 

5 name job 



svfo EXAMPLE- 1 .f o. 
sfo -pi 66;di -pg 

salary age 



isplay_empl oyee; sfo -rs 



s 


f 


St 


ci ty 


e 


a 


at 




X 


m 


e 





abel 


1 


14555 . 


.01 


36 


m 


s 


ak 


j uneau 


abel 1 


2 


1 3000 . 


.01 


55 


f 


m 


az 


phoeni x 


abernathy 


3 


12500. 


01 


61 


m 


d 


ca 


f resno 


abodoura 


5 


1 2900 . 


.01 


61 


m 


m 


ca 


sacramento 


aboe 


4 


10201 . 


.01 


41 


f 


s 


ca 


1 os angel es 


abraham 


6 


1 5000 . 


.01 


25 


f 


d 


ca 


san diego 


(46 data 


1 i nes ) 
















baker 


1 


12000 


. 10 


71 


m 


s 


i 1 


spr i ngf ield 



line 1 

Save the current values of format options as a subsystem exec_com 
(EXAMPLE-l.f o.display_employee) which can be restored later with the 
restore_format_options request. Then reset all options to their default values. 

line 2 

Set page_length (-pi) to 66 lines, and display page 1. 
lines 5-64 

System display — note that the report has reverted back to its original format (i.e., it 
is now the same as the first example in this sample user session). 

At this point you may wish to terminate the display_employee session by entering: 



65 ! di spl ay_empl oyee : q 

66 (Multics ready message) 
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Restoring a Saved Report 

The report saved in the previous example may be recalled at will. Assuming you want to have 
the report printed, then the following sequence of events must be set up: 



d i sp 1 ay_emp 1 oyee 
d i sp 1 ay_emp 1 oyee : 
d i sp 1 ay_emp 1 oyee : 



rsfo EXAMPLE- 1 
di -nr -pg 1 



04/29/83 



Sample Report 



10:26 



NAME 



JOB 



SALARY 



AGE 



SEX 



STATE 



69 



71 ! 



CITY 



abel | 


1 I 


$14 , 555 


01 | 


36 | 


mal e 


s 


ak 


| juneau 


abell | 


2 I 


$13,000 


01 j 


55 j 


f emal e 


m 


az 


| phoenix 


a<M0RE> | 


3 I 


$12, 500 


01 | 


61 | 


mal e 


d 


ca 


| fresno 


a<M0RE> | 


5 I 


$12,900 


01 | 


61 | 


mal e 


m 


ca 


| sacramento 


aboe j 


4 i 


$10, 201 


01 i 


41 j 


female 


5 


ca 


j los angel es 


(43 data 


i nes ) 














azer | 


5 I 


$12, 600 


01 I 


44 | 


ma 1 e 


S 


va 


j norfork 










Page 










d i sp 1 ay_emp 1 oyee : 


di -of 


exampl e 


-1 
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lines 3-4 

Set up for restoring the saved format options. 

line 5 

Display page 1 of the report as a verification (i.e., is this the desired report?), 
lines 9-69 

System display — note that the report is restored to its original condition (i.e., 
restored to the same format as that shown in the example under "Special Editing of a 
Report" above). 

line 71 

Write the complete formatted report to permanent storage in the user's working 
directory with pathname of "example-1". 



The full report (example-1), along with the saved format options segment 
(EXAMPLE-1. fo.display_employee) now resides in the user's working directory and may be 
dprinted or retained in permanent storage at the user's discretion. 



2-29 



GB63-00 



GENERAL COLUMN OPTIONS 

The following examples look at the "general column options." These options remain in effect 
only for the duration of the current set of columns. Every time a new set of columns is selected, 
new default values are assigned. The options are listed (through use of the list_format_options 
request) when their value is different from the default, or when asked for by name. 



di spl ay_empl oyee : lsfo 


-co 








-col umn_order 


"name job salary age 


sex 


f am i 1 y 


state city" 


di spl ay_empl oyee : sfo 


-CO 8 7 1 2 3 4 5 6;di -pg 


1 






04/29/83 


Sample Report 






10:28 


CITY j STATE | 


NAME | JOB | SALARY 


AGE 


| SEX | F 










I I A 










I I M 

I I 1 










1 1 L 










1 1 Y 


juneau | ak | 


abel | 1 | $14,555. 


01 


36 


| male | s 


phoenix | az j 


abel 1 | 2 | $13,000. 


01 


55 


| female | m 


fresno | ca j 


a<MORE> | 3 | $12,500. 


01 


61 


| male | d 



(45 data 1 i nes ) 
norfork I va 



$12, 600 . 0 1 



44 male 



67 



Page 1 - 



line 1 



List the current names and order of the report columns. 



line 4 



Reorder the sequence of report columns, and display page 1. 



lines 8-67 

System display — note that the column order has been changed from that displayed 
in the previous example. 
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74 ! di sp 1 ay_emp 1 oyee : lsfo -ex 

75 -exclude 



77 ! di spl ay_empl oyee : sfo -ex age job;di -pg 1 
81 04/29/83 Sample Report 

STATE | CITY | NAME | SALARY 



ak 
az 
ca 



juneau 
phoeni x 
f resno 



(45 data 1 ines) 
I norfork 



abel 
abel 1 
a<M0RE> 



$14,555.01 
$13,000.01 
$12, 500 . 0 1 



10 



SEX 



mal e 
f emal e 
mal e 



31 

F 
A 
M 
I 
L 
Y 

s 
m 
d 



$12,600.01 male 



140 



Page 1 



line 74 

List columns currently excluded from the report, 
line 75 

System display — the response is "", meaning that no columns are currently 
excluded. 

line 77 

Exclude the age and job columns, and display page 1. 
lines 81-140 

System display — note that the age and job columns have been excluded from the 
report (i.e., the report now consists of six columns of data instead of the eight 
previously included). 



142 ! di spl ay_empl oyee : sfo -ex "";lsfo -ex 

143 -exclude 



Execution of line 142 restores the age and job columns previously excluded by execution of line 
77. Line 143 is the system display indicating that no columns are currently excluded. 
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The next few examples look at the "group" option which is used in conjunction with other 
requests. This option is used to define a "group" of rows based on the content of one or more 
columns. 



145 ! di spl ay_empl oyee 

146 -group 



Isfo -gr 



148 ! di spl ay_empl oyee : 

149 -outl i ne 



sfo -gr state city sex; lsfo -out 



151 
155 



201 



d i sp 1 ay_emp 1 oyee : 


sfo -out sex;di 


-sort 


state city sex 


"Da 1 


, 2 




04/29/83 


Sample Report 






10: 


33 


STATE | CITY 


| NAME | 
1 1 


JOB | 
1 


SALARY | 

l 


AGE 


I SEX | 
| | 


F 


| 
| 


1 1 

| 1 
i 1 


1 

1 
i 




I 

I 
I 




1 1 

1 1 
1 1 

I 1 

! 1 


A 
M 
I 


| 


1 1 


I 




I 




I 1 
1 1 


|_ 


| 


1 1 
i i 


I 
i 




I 




1 1 
1 1 


y 


ak | juneau 


| Pambry | 


10 | 


$1 1 ,501 . 


.01 | 


66 


| female | 


d 


1 


| gaskins | 


6 ! 


$14,700. 


,01 | 


31 


! 1 


s 


1 


| justin | 


2 I 


$12, 000 , 


•01 I 


78 


I I 


m 


( 1 6 data 1 i nes ) 
















az | phoenix 


| abel 1 | 


2 I 


$13, 000 . 


■ot | 


55 


| female | 


m 


1 


| c<M0RE> | 


22 | 


$18, 300 . 


01 i 


38 


1 1 


d 


1 


1 june 


18 | 


$10,900. 


■01 I 


73 


1 1 


s 


( 12 data 1 ines) 
















| tucson 


| monaco | 


20 | 


$12, 300 . 


01 I 


30 


| female | 


d 


1 


| nevitte | 


15 | 


$12, 300 . 


01 | 


77 


1 1 


s 


! 


j pauley \ 


10 | 


$11, 600 . 


01 I 


56 


1 ! 


m 


1 


| n<M0RE> | 


5 I 


$12, 400 


•01 I 


57 


| male | 


m 


1 


| ordeman | 


1 I 


$15, 200 . 


01 I 


21 


I i 


d 


ca | fresno 


| bane j 


13 | 


$15,200. 


01 I 


50 


! female | 


m 


(6 data 1 i nes ) 
















1 


| a<M0RE> | 


3 I 


$12, 500 . 


01 I 


61 


| male | 


d 


1 


| c<M0RE> j 


23 | 


$12, 400 . 


01 I 


53 


1 1 


s 


i 


| jupiter | 


19 | 


$ 4, 100. 


01 I 


47 


1 1 


m 



214 



- Page 1 - 
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This ends the first page of the report (refer to line 151 that set up a two-page display). The second 
page of the report immediately follows the commentary describing the setup for page 1. 



line 145 

List the columns currently set for grouping purposes, 
line 146 

System display — no current grouping set. 
line 148 

Set grouping for columns (state, city, and sex), and list the columns currently set as 
candidates for duplicate suppression. 

line 149 

System display — no current outline set. 
line 151 

Set the outline column value to "sex." The outline option is used to suppress 
duplicate columns. Outlining is done when the value of a column is the same for the 
current row as it is on the previous row. Outlining is never done when it is the first 
row of a new page. The example sets outlining for the sex column. The sex column is 
the most minor column in the group and therefore all columns more major have 
outlining done also. The second request on the line invokes display (with sort) of 
pages 1 and 2. First the data has to be sorted so that use of this option can be further 
described in later examples. 
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The following example is page 2 of the report invoked by the second request on line 151. 



04/29/83 



Sample Report 



10:33 



STATE 


CITY 


| NAME j 
1 i 
1 1 
1 i 


JOB 


SALARY | 

I 
I 
I 


AGE 


SEX 


ca 


f resno 


I | 

! i 
j | 

| 1 eel and | 


14 


$32,800 


1 

| 

01 I 


77 


mal e 






| m<M0RE> | 


9 


$10,200 


01 I 


32 








i mcclung j 


5 


$13, 100 


01 i 


71 








| m<M0RE> | 


1 


$14, 100 


01 I 


26 








| monger | 


21 


$12,600 


01 I 


61 






1 os angel es 


| aboe 


4 


$10,201 


01 I 


41 


f emal e 


. (37 


data 1 i nes ) 
















san diego 


| abraham j 


6 


$15,000 


01 I 


25 


f emal e 






| c<M0RE> j 


2 


$13, 000 


01 I 


44 








| kang j 


22 


$19,201 


01 i 


23 








1 levy i 


18 


$10,800 


01 I 


66 








| m<M0RE> | 


13 


$14,800 


01 I 


71 








| mccrary | 


8 


$13, 000 


01 | 


25 





- Page 2 - 
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Sorting is done completely within the report writer. The values must all be retrieved from 
the subsystem before sorting can be done. When display is invoked without control arguments, 
the system defaults to a new retrieve on each invocation. The next two examples show how this 
retrieve can be kept and then recalled. 



234 



di spl ay_empl oyee : di 


-sort state 


city sex 


-kr -pg 


2 






04/29/83 


Sample Report 






10: 


STATE | CITY 
1 


| NAME 

j 
j 
j 


JOB | 
| 
j 
| 


SALARY | 


AGE 


SEX | 


ca | fresno 


| 

| lee land 


14 | 


$32,800. 


01 | 


77 


mal e | 




| m<M0RE> 


9 | 


$10,200. 


01 j 


32 






| mcclung 


5 I 


$13, 100. 


01 | 


71 






| m<M0RE> 


1 | 


$14, 100. 


01 j 


26 




■ 

1 


j monger 


~ j i 
^ 1 1 


$12, 600 . 




61 


i 


| los angel es 


| aboe 


4 | 


$10,201 


01 I 


41 


female | 


(37 data 1 ines) 














| san diego 


| abraham 


6 | 


$15, 000 


01 | 


25 


female | 




j c<M0RE> 


2 I 


$13, 000 


01 | 


44 






| kang 


22 | 


$19, 201 . 


01 | 


23 






| 1 evy 


18 | 


$10,800. 


01 I 


66 






| m<M0RE> 


13 | 


$14 , 800 


01 | 


71 




i 
I 


j mccrary 


8 I 


$13, 000 


oi ! 


25 


! 



34 



279 



Page 2 
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line 216 

Sort the state, city, and sex columns; then display page 2. In addition, keep the 
results of the retrieve. 



lines 220-279 

System display. 

The sorted data is now retained for future use (see -kr on line 216). Future display requests may 
now re-call the kept data (i.e., the amount of system time required after execution of line 216 
until the report is displayed can be minimized in future displays). 



281 ! di spl ay_empl oyee : di -kr -or -pg 2 



The display results (provided by execution of line 281) would be an exact copy of that provided in 
lines 220-279 above, except that the time required to produce the report is less. 
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Outlining can also be done on columns which are not a member of the group. For example: 



283 ! di spl ay_empl oyee : lsfo -out 

-out! ine "sex 1 



286 ! display_emp1oyee~: sfo -out sex family 
288 ! display_emp1oyee: di -kr -or -pg 1,2 



292 



04/29/83 
STATE I 



CITY 



338 



ak I juneau 
I 

I 

( 16 data 1 ines) 

az | phoenix 

I 
I 

( 12 data 1 ines) 

| tucson 

I 

I 

i 

I 

ca | fresno 
(6 data 1 ines) 



NAME 



Sample Report 



JOB 



| bambry | 
| gaskins | 
| justin j 



abel 1 
c<M0RE> 
j une 



monaco | 

nevitte | 

pauley | 

n<M0RE> j 

ordeman | 

bane I 



a<M0RE> | 
c<M0RE> | 
jupiter | 



SALARY 



10 ] $11 ,501 .01 | 
6 j $14,700.01 | 
2 I $12,000.01 



2 | $13,000.01 | 
22 | $18,300.01 | 
18 ] $10,900.01 ] 



20 I $12,300.01 

15 | $12,300.01 

10 | $11,600.01 

5 | $12,400.01 

1 | $15,200.01 

13 $15,200.01 



3 | $12,500.01 | 
23 | $12,400.01 | 
19 j $ 4, 100.01 | 



10:36 

AGE | SEX | F 

I I A 

I I M 

I I I 

I I L 

I I Y 

66 | female j d 

31 I |s 

78 | | m 



55 
38 

73 



30 | 
77 | 

56 j 

57 | 
21 | 
50 I 



61 
53 
47 



female | m 

I d 
! s 



female 



mal e 



f emal e 



mal e 



351 



- Page 1 - 
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line 283 

List the columns currently set as candidates for duplicate suppression, 
line 286 

Set the outline column value to "sex" and "family." (Refer to additional description 
regarding outlining in the commentary of line 151 above.) 

line 288 

Display page 1 and 2 using the data retrieved during the previous invocation (-or), 
and keep the retrieved data (-kr) from this execution for use in subsequent 
invocations of the display request. 

lines 292-351 

System display — note that the family entry for line 338 is blank indicating duplicate 
suppression of "m" which would normally have displayed (see line 201 above). 

Page 2 of the report is not shown. 
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The size of a retrieved table can cause a process directory quota overflow when working with 
large tables. The -temp_dir control argument for the display request allows the user to provide a 
directory for the retrieved table where enough quota is available. The -temp_dir argument can 
only be used when requesting a new table. 



353 ! di spl ay_empl oyee : di -or -kr -td [e wd] -pg 1 

354 di spl ay_empl oyee (display): Warning: The temp_dir 

>udd>Demo>disp1ay_emp1oyee won't be used. 



line 353 

Display page 1 using the data retrieved during the previous invocation (-or), and 
keep the retrieved data (-kr) from this execution utilizing the temporary directory 
"wd". 

line 354 

System display — warning message because a new retrieval was not requested (i.e., 
-old retrieval was used). 

Page 1 of the report is not shown. It would be an exact duplicate of that shown in lines 292-351 
above. 



356 ! di spl ay_jempl oyee : di -kr -td [e wd] -pg 1 -sort state 
city sex 



line 356 

Display page 1 using a new retrieval, keep the retrieved data for future use, and 
utilize "wd" for a temporary directory. 

Page 1 of the report is not shown. It would be an exact duplicate of that shown in lines 292-351 
above. 
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358 ! 




1 ay_en 


iplcyee: e Is 


359 


Segments = 


: 224, Length = 353 


360 








361 


rew 


0 


! BBB JNHFGnQJX 1 w . temp . 0565 








( data 1 i nes ) 


369 


r w 


0 


! BBB JNHFGmXFcFB . RW . tab! e 


370 


r w 


1 


EXAMPLE- 1 . f o . d i spl ay_empl oyee 


371 


r w 


1 


sex_l ookup . d i sp 1 ay_empl oyee 



line 358 

Escape out of display _employee and list the current contents of the working 
directory. 

lines 359-371 

System display — lines 359-369 outlines the areas used f or the temporary directory. 
Note that line 370 is associated with an earlier example where the contents of a 
report was saved (refer to "Saving a Report and Resetting Options"), and line 371 
identifies the segment which contains the exec_com used to change "m" and "f" to 
"male" and "female" for the sex column (refer to "Special Editing of a Report"). 



375 ! di spl ay_empl oyee : 1 sf o -pb 

376 -page_break "" 

378 ! di spl ay_empl oyee : sfo -pb state; di -kr -or -pg 1,4 



lines 375-378 

is a request to list the current columns that are candidates for new page breaks, and 
line 376 says there are no current candidates. The following four examples show 
full-page representations of the results of the requests in line 378 (set page break 
value to "state" and display pages 1 through 4). 
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04/29/83 

STATE I CITY 



ak 



juneau 



NAME 



Sample Report 



JOB 



10:39 



bambry 
gask i ns 
j ust i n 
mad eod 
manuel 
m<M0RE> 
m<M0RE> 
nesl i ne 
ord 
abel 
cooke 
j ones 
1 edger 
macl ure 
m<M0RE> 
mead 
mol 1 oy 
nevl i ng 
paul 



10 
6 
2 
22 
18 
13 
8 
4 
24 
1 

21 
16 
1 1 
7 
3 
23 
19 
14 
9 



SALARY 



$11 ,501 .01 
$14,700.01 
$12,000.01 
$18,500.01 
$10,000.01 
$14,900.01 
$13,000.01 
$10, 100.01 
$ 9,200.01 
$14,555.01 
$12, 100.01 
$13,000.01 
$21 ,900.01 
$14,700.01 
$12, 100.01 
$12,700.01 
$ 4,300.01 
$32,500.01 
$10,300.01 



AGE 



66 
31 
78 
43 
33 
67 
77 
27 
34 
36 
34 
21 
27 
53 
71 
29 
22 
63 
73 



SEX 



f emal e 



mal e 



( 10 bl ank 1 i nes ) 



- Page 1 - 
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04/29/83 

STATE I CITY 



phoenix 



tucson 



( 10 blank 1 ines) 



Sample Report 
NAME I JOB 



SALARY 



abell ] 


2 


$13 


000 


01 | 


55 


fema 1 e 


m 


c<M0RE> | 


22 


$ 18 


300 


01 j 


38 






j une j 


18 


$ 10 


900 


01 | 


73 






lednar | 


13 


$15 


000 


01 | 


7 1 




m 


m<M0RE> | 


8 


$12 


600 


01 j 


37 




d 


m<M0RE> | 


4 


$10 


800 


01 j 


68 




s 


meadow | 


24 


$ 9 


800 


01 j 


52 




m 


bander | 


1 1 


$21 


100 


01 I 


70 


mal e 


s 


geist j 


7 


$14 


600 


01 | 


21 




m 


kane j 


3 


$12 


300 


01 j 


58 




d 


mac! i n j 


23 


$12 


500 


01 j 


79 




s 


manzo j 


19 


$ 4 


200 


01 j 


74 




m 


mccoy | 


14 


$31 


300 


01 j 


67 




d 


meagher | 


9 


$10 


500 


01 | 


52 




s 


dupu i s | 


12 


$12 


000 


00 I 


28 




y 


monaco j 


20 


$12 


300 


01 j 


30 


f emal e 


d 


nevitte | 


15 


$ 12 


300 


01 | 


77 




s 


pau 1 ey | 


10 


$1 1 


600 


01 | 


56 




m 


n<M0RE> | 


5 


$12 


400 


01 j 


57 


mal e 




ordeman ] 


1 


$15 


200 


01 j 


21 




d 



AGE 



SEX 



10:40 
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04/29/83 



Sample Report 



10:40 



STATE 



CITY 



f resno 



los angeles 



( 10 data 1 ines ) 



sacramento 



NAME | 

| 


JOB 


SALARY | 


AGE 


SEX 


F 
A 
M 
I 


| 

bane | 


1 3 




n 1 I 


50 


■p pma "1 ei 


|_ 

1 Y 
m 


george 1 


8 




n 1 1 


44 




1 d 


kang ^ 


4 




n 1 I 


76 




i ^ 


mac lure 


24 




n 1 I 


47 




1 ^ 


marcey 1 


20 


<t i o con 


n 1 I 
U 1 I 


7 1 




1 rl 


mccrary 


1 5 




n 1 I 


53 




1 ^ 


meak i n i 


10 


$11, Ot/U 


r\ 4 I 
U 1 | 


5 1 






a<M0RE> 1 


3 


3> 1 *d , DUU 


U 1 | 


6 1 


male 


1 H 

1 


c<M0RE> 1 


23 


$12, 400 


01 | 


o o 




1 ^ 


j up i ter I 


1 9 


$ 4, 100 


01 | 


47 






i oc i a nri ! 

1 CC 1 Ol IU 1 


1 4 


$32,800 


01 | 


77 




1 H 
1 ^ 


m<MHPF> 1 

! 1 1 ^ ["1 l\ I ^ i 


g 


$10,200 


01 j 


TO 




1 s 


mcclung | 


5 


tiq « nn 


n -t i 

U I | 


71 




m 


m<MCRE> | 


1 


4> i *+ , i 


V 1 [ 


26 




1 ci 


monger | 


21 




O 4 1 

«J ' I 


61 




s 


aboe | 


4 


a- 1 n on * 


n 4 I 
U l | 


41 


f emal e 




cowes ! 


24 


<t Q son 


U i ( 


58 






j ust i n ! 


20 


$ 1 / , MU(J 


O 4 1 

V \ [ 


34 




1 rl 


1 ppc + m?i 1 


1 5 


<t 1 o Tnn 


Pi H 1 

U 1 I 


CQ 




1 ^ 


m<M0RE> 1 


1 0 


<t 1 i /inn 


O 4 [ 

U i 1 


CO 




[ m 


m<M0RE> 1 


6 


a: h c nnn 


U 1 I 


26 




1 H 


mpa 1 aw 1 
nico icy 


1 ■) 


to 1 cnn 


0 1 1 


Ju 




1 H 


ne v i 1 1 e 


7 


4; 1 a Qnn 


n 1 I 






s 


or *f 


3 


<t 1 o Ann 


U l 1 


' u 




m 


barrett i 


1 5 


<t 1 o ann 


n 4. 1 


cc 

O 3 


T crMlcL 1 fcr 


s 


gill 1 


•JO 


c 1 1 ft no 


n i 1 


47 




m 


keene I 


g 


$14,1 O0 


0 1 I 


54 






m<M0RE> 1 


2 


$12, 200 


01 | 


54 






marcy j 


22 


$19,700 


01 I 


45 






m<M0RE> j 


18 


$10,900 


01 I 


62 




d 


means j 


13 


$14,300 


01 | 


46 




s 


newcomb | 


8 


$12, 300 


01 I 


36 




m 


orlaens | 


4 


$10,300 


01 I 


41 




d 


a<M0RE> j 


5 


$12, 900 


01 j 


61 


mal e 


m 


c<M0RE> j 


1 


$14,300 


01 j 


50 




d 


kane ) 


21 


$12, 400 


01 | 


24 




s 


leonard | 


16 


$12, 900 


01 j 


25 




m 


macnabb | 


1 1 


$21 , 500 


01 ! 


68 




d 


mccoy | 


7 


$14, 000 


01 I 


77 j 




s 
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04/29/83 
STATE 



Sample Report 



10:40 



CITY 



sacramento 



san diego 



san francisco 



(8 data 1 ines) 



santa cruz 



NAME | 

j 
j 
| 


JOB 


SALARY | 

i 

1 


AGE 


SEX 


j 

meakin j 


3 


$12,900 


01 j 


"7 4 

/ 1 


ma 1 e 


monson | 


23 


$13, 000 


01 | 


40 




newman | 


19 


$ 4,200 


01 | 


68 




payne | 


14 


$30, 400 


01 | 


30 




abraham j 


6 


$15, 000 


01 j 


25 


f emal e 


c<M0RE> | 


2 


$13, 000 


01 | 


44 




kang 1 


22 


$19 201 


01 I 


23 




1 evy J 


18 


$10,800 


01 | 


66 




m<M0RE> | 


13 


$14,800 


01 j 


71 




mccrary | 


8 


$13, 000 


01 | 


25 




mealey j 


4 


$10,700 


01 j 


7 1 




montano | 


24 


$ 9,300 


01 j 


22 




newton | 


20 


$13, 100 


01 | 


24 




peacock | 


15 


$12, 500 


01 | 


76 




b<M0RE> | 


16 


$12,310 


01 j 


63 


mal e 


keener | 


7 


$14 , 000 


01 | 


62 




m<M0RE> | 


3 


$12, 400 


01 j 


63 




m<M0RE> | 


23 


$12, 600 


01 | 


38 




m<M0RE> | 


19 


$ 4 , 000 


01 j 


22 




mecham | 


14 


$30, 400 


01 I 


23 




nnuhs 1 I 1 


g 


* h rs ir\r\ 


r\ -t I 






o<M0RE> | 


5 


$12, 900 


01 | 


27 




baur i 


18 


$10, 1 00 


01 | 


79 


f emal e 


abrahms | 


7 


$14,300 


01 | 


35 


mal e 


c<M0RE> j 


3 


$12,501 


01 j 


76 




katz j 


23 


$12, 500 


01 i 


58 




] ibin ] 


19 


$ 4,000 


01 j 


29 




macna i r | 


14 


$31 ,300 


01 I 


70 




mccory | 


9 


$10,500 


01 | 


52 




means \ 


5 


$12,900 


01 | 


60 




monte | 


4 


$15, 300 


01 i 


31 




nguyen 1 


21 


$12,700 


01 I 


53 




parce | 


16 


$12, 900 


01 j 


68 




nevl ing | 


6 


$14 ,400 


01 | 


37 


f emal e 


orend | 


2 


$12, 900 


01 j 


72 




newcomb | 


16 


$12,400 


01 | 


72 


mal e 


paulson | 


1 1 


$21 , 100 


01 j 


49 
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Now we will experiment with column subtotals and totals. A subtotal specification is given in the 
form of one or more "triplets." A triplet is given as the column to be sub totaled, followed by the 
column whose value change should generate the subtotal, and optionally followed by "reset" or 
"running" to indicate what type of subtotal is desired. Reset is the default. In the following 
example, lines 1-8 are intentionally left blank. 



9 ! di spl ay_empl oyee : sfo -rhv " " -rfv "" 

11 ! dl spl ay_emp1 oyee : Isfo -stt 

12 -subtotal 

14 ! di spl ay_empl oyee : sfo -stt sal ary , state , reset 



line 9 

Set row header and row footer values to "default." 
lines 11-14 

List current value for subtotal, and set up new value. 

The subtotal inherits its width, editing request, etc. from the parent column. The width of the 
salary column must be increased or the subtotal is folded, and a larger picture is needed to edit it 
through. The age and job columns are left at their present width so the filling of numbers can be 
seen later when the numbers become large enough. 
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1G ! display_employee: lsfo -wid salary 
17 -width salary "10" 

19 ! display_emp1oyee: sfo -wid salary 14 

21 ! display_employee: lsfo -ed salary 

22 -editing salary 



"[e pic $zz,zz9v.99 [civ salary]]" 



24 ! di spl ay_empl oyee : sfo -ed salary "[e pic $zz , zzz , zz9v . 99 [civ salary]]" 

26 ! di spl ay_empl oyee : lsfo -al salary 

27 -alignment salary "decimal 8" 



29 ! d i sp 1 ay_emp 1 oyee : sfo -al salary decimal 12 

31 ! display_employee: di -nr -kr -sort state city sex -pg 1,4 



35 04/29/83 
STATE 



ak 



CITY 



j uneau 



NAME 



Sample Report 



JOB 



Pambry 
gask i ns 

j ust i n 



10 
6 
2 



SALARY 



1 1 ,501 .01 
14,700.01 
12,000.01 



AGE 



66 
31 
78 



SEX 



10:42 

F 
A 
M 
I 
L 
Y 



feme 1 e 



( 1 5 data 1 i nes ) 



64 ak i 

(30 blank 1 i nes ) 

95 



paul 



9 J $ 10,300.01 
| 

I $ 262,056.19 



Page 1 



73 
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lines 16-29 

List current value for width, editing, and alignment of the salary column, 
and set up new values. 

line 31 

Display pages 1 through 4 of the report, starting with a new retrieval, sorting the 
report as indicated to get back into the full format, 
and keep the retrieval for re-use. 

lines 35-281 

System display — note the inclusion of subtotals in the salary column 
(total by state — see lines 64, 127, and 276). The remaining three 
pages of the report follow. 
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97 04/29/83 



Sample Report 



10:42 



STATE | 



CITY 



NAME 



JOB 



SALARY 



az | phoenix 
I 

( 13 data 1 ines) 
I tucson 



127 az 



157 



(31 blank 1 ines) 



| abell 
| c<M0RE> 



| monaco 

| nevitte 

| pauley 

| n<M0RE> 

I ordeman 



2 
22 



20 
15 
10 
5 
1 



13,000.01 
1 8 , 300 . O 1 



12,300.01 
1 2 , 300 . 0 1 
1 1 ,600.01 
12,400.01 
1 5 , 200 . O 1 



$ 272,700.19 



AGE | SEX | F 

I I A 

I I M 

I I I 

! I L 

I I Y 

55 | female | m 

38 I d 



30 I female 

77 | 

56 I 

57 | male 
21 I 



- Page 2 
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STATE 



CITY 



ca | fresno 

( 14 data 1 ines) 

I 1 os angel es 
i 

(17 data 1 ines) 

| sacramento 

I 

( 12 data 1 ines) 



NAME 



Sample Report 



JOB 



bane 



aboe 
cowes 



barrett 
gi 1 1 



4 | $ 
24 $ 



15 | $ 
10 I $ 



SALARY 



13 $ 15,200.01 



10,201 .01 
9,500.01 



12,800.01 
1 1 ,800.01 



10:42 

| AGE | SEX | F 
I A 
I M 
I I 
I L 
I Y 

50 I female | m 



41 | female I 
58 I m 



65 | female | s 
47 m 



219 



mccoy I 7 I $ 14,000.01 | 77 

- Page 3 - 
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221 04/29/83 



Sample Report 



10:43 



STATE 



CITY 



NAME 



JOB 



SALARY 



AGE 



SEX 



281 



! Sacramento 


1 meak i n 


1 3 


! $ 


1 2 , 900 . 


■01 I 


71 I 


mal © 


1 ™ 


I 


| monson 


| 23 


I $ 


13,000. 


.01 | 


40 | 


1 


1 d 


I 


| newman 


1 19 


I $ 


4 , 200 . 


01 | 


68 | 


1 


I s 


I 


| payne 


I 14 


I $ 


30 , 400 . 


.01 | 


30 | 


i 


1 m 


j san diego 


| abraham 


I 6 


i $ 


1 5 , 000 . 


01 i 


25 | 


female 


i d 


| 


| c<M0RE> 


I 2 


I $ 


1 3 , 000 . 


01 I 


44 I 


1 
I 


! s 


( 16 data 1 i nes ) 


















| san francisco 


| baur 


1 18 


I $ 


10, 100. 


.01 | 


79 | 


female 


1 d 


1 


| gnandt 


I 13 


I $ 


14,700. 


.01 | 


60 | 


1 


1 s 


( 17 data 1 i nes ) 


















| santa cruz 


| nevl i ng 


I 6 


! $ 


1 4 , 400 . 


• 01 ! 


37 | 


female 


! d 


1 


| orend 


I 2 


I $ 


1 2 , 900 . 


■01 I 


72 | 


1 


1 s 


1 


| newcomb 


I 16 


I $ 


12,400 


01 I 


72 | 


mal e 


1 n. 


1 
1 


| paulson 
1 


! 11 

I 


I $ 


2 1 , 1 00 


.01 | 


49 | 


1 


! d 


1 


1 


I 


! -- 
I $ 


1 ,281 ,323 


— I 

.94 | 


I 


1 

1 


1 
1 


(4 bl ank 1 i nes ) 






















- Page 


4 - 
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The following example shows how to get subtotals for multiple columns in addition to more than 
one subtotal per column. 



1 ! di spl ay_empl oyee : sfo -stt -prompt 

2 Enter -subtotal . 

3 ! age, sex salary, sex job, sex age, city salary, city job, city age, state 

4 ! salary, state job, state 

5 ! . 



7 ! di spl ay_empl oyee : di -or -kr -pg 1,3 
11 04/29/83 Sample Report 



10:43 



STATE 



ak 



CITY 



j uneau 



( 5 data 1 i nes ) 



ak 



46 ak 



j uneau 



j uneau 



49 ak 

(22 blank 1 i nes ) 



NAME | 


JOB 




SALARY 




AGE 


SEX 


| 
| 

bambry | 


10 


$ 


1 1 ,501 


01 | 


66 


f emal e 


gaskins 1 


6 


$ 


14.700 


01 i 


31 




justin | 


2 


$ 


12,000 


01 | 


78 




macleod | 


22 


$ 


1 8 , 500 


01 I 


43 




manuel | 


18 


$ 


10,000 


01 | 


33 




m<M0RE> | 


13 


$ 


14,900 


01 j 


67 




m<M0RE> | 


8 


$ 


1 3 , 000 


01 | 


77 




nes 1 i ne | 


4 


$ 


10, 100 


01 | 


27 




ord j 


24 


$ 


9,200 


01 j 


34 






107 


$ 


1 13,901 


09 | 


456 


f emal e 


abel | 




$ 


14,555 


01 i 


36 


mal e 


mead \ 


23 


$ 


1 2 . 700 


01 ! 


29 




molloy | 


19 


$ 


4,300 


01 j 


22 




nevl i ng | 


14 


$ 


32 , 500 


01 | 


63 




paul | 


9 


$ 


10,300 


01 | 


73 






124 


$ 


148, 155 


10 | 


429 


mal e 




231 


$ 


262,056 


19 | 


885 






231 


$ 


262,056 


19 | 


885 





71 
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line 1 

Request to set columns for sub totaling, with prompt. 

line 2 

System display — prompt, 
lines 3-5 

Set column values to be subtotaled, and terminate the prompt. 

line 7 

Display pages 1 through 3. 
lines 11-195 

System display — the display of pages 2-3 follow. 
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04/29/83 Sample Report 10:43 



STATE | CITY 


| NAME | 

I | 
I 

' ! 


JOB 




SALARY 


1 
1 
1 
1 


AGE 


SEX 


| 

az | phoenix 


j ] 

| abel 1 | 


2 


$ 


1 3 , 000 


[ 

01 | 


55 


f ema 


I 


| c<M0RE> | 


22 


$ 


18, 300 


01 j 


38 




I 


1 J une | 


18 


$ 


10,900 


01 j 


73 




I 


| lednar j 


13 


$ 


1 5 , 000 


01 | 


71 




I 


| m<M0RE> | 


8 


$ 


1 2 , 600 


01 | 


37 




I 


| m<M0RE> | 


4 


$ 


10,800 


01 j 


68 




I 
I 


| meadow | 
1 1 


24 


$ 


9,800 


01 j 


52 




' 


1 ' 


91 


$ 


90,400 


I 

07 | 


394 


f ema 


! 


| bander | 


1 1 


$ 


21 , 100 


01 | 


70 


mal e 




| geist | 


7 


$ 


14,600 


01 | 


21 






| kane | 


3 


$ 


1 2 , 300 


01 | 


58 






| macl i n | 


23 


$ 


12,500 


01 ! 


79 






| manzo j 


19 


$ 


4 , 200 


01 | 


74 




i 


| mccoy j 


14 


$ 


3 1 , 300 


01 | 


67 






| meagher j 


9 


$ 


10,500 


01 I 


52 




I 


| dupuis | 


12 


$ 


1 2 , 000 


00 | 


28 




| phoenix 




98 


$ 


118, 500 


07 i 


449 


mal e 


I 

| phoenix 


1 I 
' 1 


189 


$ 


208 , 900 


— I 

14 | 




843 




| tuoson 


| monaco | 


20 


$ 


1 2 , 300 


01 | 


30 


f ema 




| nevitte | 


15 


$ 


1 2 , 300 


01 | 


77 






| pauley | 


10 


$ 


1 1 , 600 


01 | 


56 




! 




45 


$ 


36 , 200 


03 | 


163 


f ema 


i 


| n<M0RE> | 


5 


$ 


1 2 , 400 


01 | 


57 


mal e 




j ordeman | 


1 


$ 


1 5 , 200 


oi ! 


21 




az | tucson 




6 


$ 


27, 60 


02 | 


78 


mal e 


az | tucson 




51 


$ 


63 , 800 


05 j 


241 




az | 




240 


$ 


272,700 


19 j 


1084 





( 10 bl ank 1 ines ) 
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135 04/29/83 



Sample Report 



10:44 



STATE 



ca 



CITY 



f resno 



f resno 

f resno 

los angel es 



NAME | 
I 

| 

1 


JOB 




SALARY 


I 

! 
I 


AGE 


SEX 


bane | 


13 


$ 


1 5 , 200 


oi ! 


50 


f ernal e 


george | 


8 


$ 


12, 100 


01 | 


44 




kang j 


4 


$ 


10,000 


01 j 


76 




mac lure | 


24 


$ 


9,700 


01 I 


47 




marcey j 


20 


$ 


i 2 , 600 


01 j 


71 




mccrary | 


15 


$ 


1 2 , 500 


01 | 


53 




meakin j 


10 


$ 


1 1 , 600 


01 j 


51 




1 


94 


$ 


83,700 


— I 

07 | 


392 


f emal e 


a<M0RE> | 


3 


$ 


1 2 , 500 


01 | 


61 


mal e 


c<M0RE> | 


23 


$ 


1 2 , 400 


01 | 


53 




jupiter [ 


19 


$ 


4, 100 


01 | 


47 




1 eel and | 


14 


$ 


32 , 800 


01 | 


77 




m<M0RE> j 


9 


$ 


10,200 


01 j 


32 




mcclung J 


5 


$ 


13, 100 


01 j 


7 1 




m<M0RE> | 


1 


$ 


1 4 , 1 00 


01 i 


26 




monger | 


21 


$ 


12,600 


01 I 


61 




| 

| 


95 


$ 


111, 800 


I 

08 | 


428 


mal e 


| 


189 


$ 


195,500 


I 

15 i 


820 




aboe i 


4 


$ 


10,201 


01 | 


41 


f emal e 


cowes | 


24 


$ 


9,500 


01 | 


58 




justin | 


20 


$ 


1 2 , 900 


01 | 


34 




leestma | 


15 


$ 


1 2 , 300 


01 | 


69 




m<M0RE> | 


10 


$ 


1 1 , 400 


01 | 


52 




m<M0RE> | 


6 


$ 


15,000 


01 j 


26 




meagher | 


2 


$ 


1 2 , 600 


01 | 


67 




monroe | 


22 


$ 


1 8 , 900 


01 | 


42 




newhal 1 


18 


$ 


10,000 


01 | 


30 




pavlov | 


13 


$ 


1 4 , 000 


01 I 


24 






134 


$ 


126,801 


10 j 


443 


f emal e 


barker j 


14 


$ 


32,800 


01 I 


78 


mal e 



( 7 data 1 i nes ) 



195 
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This page intentionally left blank. 
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To see how the totals feature works, the last page of the report must be examined. The example 
eliminates page breaks to cut down on the number of pages generated. 



197 ! displ ay_empl oyee : sfo -tt age salary job 
199 ! di spl ay_emp1 oyee : sfo -pb " " 



Just as retrieved data can be re-used, so can formatted reports. The last few pages will be 
examined, but display will be asked to keep the formatted report. It will use the previously 
established temp_dir to place the copy of the formatted report. 
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201 ! di spl ay_empl oyee : di -kr -or -krp -pg 33,$ 



04/29/83 



Sample Report 



10:52 



STATE 



vt 



vt 



vt 



vt 



wa 



CITY 



rut 1 and 
rut 1 and 

rut 1 and 



seatt 1 e 



Seattle 

seatt 1 e 
( 13 data 1 ines) 



NAME | 

j 


JOB 




SALARY 




AGE 


SEX 


I 

nsi r» np 1 1 ! 




■p 




I 

\j i ) 


3 3 


ma 1 e 








1 TJ OfVv 


uy | 


4bb 


ma 1 e 








*£4b , Di l 


H Q 1 
1 O j 


y y z 






431 


$ 


478,51 1 


36 | 


1866 




32 1 2 | 


c 
© 




14,1 UU 


U 1 | 


"7 C 


f ema 1 e 


licit c*y i 








U i I 


bo 




j ohnson ] 






i B , yuu 


0 1 j 


25 




msc 1 ©fin j 


•i c 

1 o 




i u , uuu 


U i i 


74 






1 o 




l 4 , UUU 


U 1 i 


67 




m^MnDCs, 1 


o 
o 




1 2 , 600 


0 1 I 


72 






H 




l U , <dUU 


0 1 I 


67 




nef f | 






9 , 100 


01 | 


65 




o ' ne i 1 | 


20 


$ 


12, 100 


01 j 


49 




! 


117 


$ 


114, 000 


09 | 


560 


f emal e 


col 1 ier | 


16 


$ 


1 3 , 000 


01 | 


62 


mal e 


J wl 1 1 LrS | 


■| -| 


<t 
4> 


20 , 200 


01 I 






latter j 


7 


$ 


1 5 , 300 


01 i 


55 




m<M0RE> | 


3 


$ 


12,400 


01 j 


66 




m<M0RE> | 


23 


$ 


1 2 , 500 


01 | 


43 




mcrorie | 


19 


$ 


4,000 


01 I 


40 




mock j 


14 


$ 


30, 100 


01 j 


22 




ne i 1 1 1 


9 


$ 


10,800 


01 | 


47 




patel | 


5 


$ 


1 2 , 000 


01 j 


24 






107 


$ 


130, 300. .09 j 


409 


mal e 




224 


$ 


244 , 300 


18 | 


969 
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04/29/83 



Sample Report 



10:52 



STATE | CITY | NAME | JOB 



wa I walla walla j bahn I 7 

| | freuh | 3 

| | jones | 23 

| | macleod | 19 

| | man ion | 14 

| | m<M0RE> | 9 

| | mittal | 5 

S ] negri ] 1 

| | oong | 21 



wa | walla walla j 102 
wa j walla walla | | 220 



wa ; II 444 

wi | green bay [bailey | 8 

| | fyock | 4 

j | june j 24 

I | m<M0RE> | 20 

| | mann | 15 

| | m<M0RE> | 10 

j | mock j 6 

I | ne i 11 j 2 

I | onofiro I 22 



| | j 111 

( 1 1 data 1 i nes ) 



green bay j 103 



green bay \ | 214 

racine | c<M0RE> | 20 

| johnson | 15 

| ledford | 10 

| maclin | 6 



SALARY | AGE | SEX | F 

j ! | A 

| j j M 

I I | I 

I i I l 

I I Y 



$ 


14,900 


01 | 


55 


mal e 


d 


$ 


1 2 , 900 


01 | 


76 




s 


$ 


1 2 , 800 


01 j 


36 




m 


$ 


4,200 


01 j 


60 




d 


$ 


32 , 400 


01 i 


68 




s 


$ 


10,700 


01 j 


68 




m 


$ 


12,000 


01 I 


43 




d 


$ 


1 5 , 200 


01 j 


68 




s 


$ 


1 2 , 000 


01 j 


70 




m 


$ 


127 , 100 


--- I 

09 j 


544 


mal e 




$ 


236, 301 


18 j 


929 






$ 


480, 601 


36 | 


1898 






$ 


12,410 


01 | 


25 


f emal e 


s 


$ 


10, 801 


01 | 


47 




m 


$. 


S.210 


01 | 


A 1 
** / 




r-t 

w 


$ 


12,800 


01 | 


35 




s 


$ 


1 3 , 000 


01 | 


52 




m 


$ 


12,000 


01 j 


51 




d 


$ 


14,800 


01 I 


78 




s 


$ 


1 2 , 200 


01 j 


30 




m 


$ 


18,800 


01 j 


77 




d 


$ 


1 16,021 


09 | 


442 


f emal e 




$ 


132,200 


... | 

09 | 




473 


male 




$ 


248,221 


... j 
18 | 




915 






$ 


1 2 , 500 


01 | 


20 


f emal e 


s 


$ 


12,410 


01 | 


61 




m 


$ 


1 1 , 200 


01 I 


63 






$ 


14,200 


01 I 


25 




s 
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STATE I CITY 



Sample Report 



10:53 



racine 



( 10 bl ank 1 i nes ) 



NAM t ! 


IAD 

UUD 




SALARY 




AGE 


SEX 


F 


















A 


















M 


















I 


















L 


















Y 


iTl'v.lVlUKt 






1 2 


, 600 


0 1 


f\ r- 

3b 


f ema 1 e 


m 


m*" RAO D D ^ . 

m<lvlUKh> | 




$ 


1 8 


, 700 


01 


38 




d 


no 1 dt j 


1 a 


$ 


10 


, 200 


01 


67 




s 


n<MUKb> | 


A O 
1 o 


$ 


1 4 


, 400 


01 


7 1 




m 


patton | 


Q 

o 




1 2 


, 100 


0 1 


27 




d 




1 14 


$ 


1 18 


,310 


09 


407 


f emal e 




baker j 


9 


$ 


12 


,000 


10 


43 


male 


m 


gardner | 


5 


$ 


12 


,300 


01 


29 




d 


jupiter | 


1 


$ 


14 


,301 


01 


41 




s 


m<M0RE> | 


21 


$ 


12 


,600 


01 


32 




m 


mansour j 


16 


$ 


13 


, 100 


01 


46 




a 


mcclung | 


1 1 


$ 


21 


, 100 


01 


39 




s 


modi i n | 


7 


$ 


14 


, 300 


01 


60 




m 


nelson j 


3 


$ 


12 


,400 


01 


70 




d 


o<M0RE> | 


23 


$ 


12 


,800 


01 


62 




s 




95 


$ 


124 


,901 


18 


422 


ma 1 e 






210 


$ 


243,21 1 


27 


829 








424 


$ 


491 ,432 


45 


1744 








12279 


$13, 766, 244 


12 


48952 
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Now that the report appears correct, it can be written (saved) to a file. -old_report will be 
specified so that display uses the previously formatted report. 



203 ! di spl ay_emp1 oyee : di -orp -of S AMP LE_RE PORT -kr 



The complete report (SAMPLE_REPORT) now resides in the user's working directory and can be 
dprinted at will. The -keep_retrieval control argument was specified in order to continue this 
session, but could have been eliminated if the user was terminating the session after saving this 
report. 
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Now we will experiment with generation of a report utilizing the group footer /header and 
left/ right trim operations. 



1 ! di spl ay_empl oyee : sfo -rs 

3 ! di spl ay_empl oyee : sfo -pw 60 -tl off -pb state 

5 ! di spl ay_empl oyee : sfo -ex 1 2 3 4 5 S 7 8 -gr state city 

7 ! di spl ay_empl oyee : sfo -gft city -ght city 



9 ! di spl ay_empl oyee : sfo -gfv -prompt -ghv -prompt 

10 Enter -group_f ooter_val ue . 

11 ! ! ! ! ! 

12 ! . 

13 Enter -group_header_val ue . 

14 ! .'City: [civ city] ! ! ! 

15 ! ! ! ! ! 

16 ! . 



18 ! display_employee: sfo -phv -prompt -pfv -prompt 

19 Enter -page_header_val ue . 

20 ! IState: [civ state] ! ! ! 

21 ! ! ! ! ! 

22 ! 

23 Enter -page_f ooter_val ue . 

24 ! ! ! ! ! 

25 ! !!- Page [dib page_number] -!! 

26 ! . 



28 ! di spl ay_empl oyee : sfo -rhv -prompt 

29 Enter -row_header_val ue . 

30 ! Employee [e rtrim [civ name]] is [e ltrim [civ age]] years old and 

earns [e pic $z9 , 999v . 99 [civ salary]]!!! 

31 ! . 



33 ! di spl ay_empl oyee : di -or -kr -sort state city salary -pg 1,3 



37 State: ak 



39 City: juneau 



40 Employee molloy is 22 years old and earns $ 4,300.01 
Employee ord is 34 years old and earns $ 9,200.01 
Employee manuel is 33 years old and earns $10,000.01 
Employee nesline is 27 years old and earns $10,100.01 
Employee paul is 73 years old and earns $10,300.01 

( 12 data 1 ines) 

Employee ledger is 27 years old and earns $21,900.01 
Employee nevling is 63 years old and earns $32,500.01 

. (37 bl ank 1 i nes ) 

97 - Page 1 - 
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lines 1-5 

Resets all options (i.e., restore the report back to its original format), set page width 
to 60, turn title line "off," set the page break to "state," exclude all 8 columns of the 
report, and group the report by "state" and "city." 

line 7 

Sets the group footer /header trigger to "city." 
lines 9-16 

Sets the group footer value to a blank line (!!!!) and the group header value to "City:" 
(left- justified). 

lines 18-26 

Sets the page header value to "State:" (left- justified), the page footer (2 lines) to 
contain a blank line (!!!!), and the second footer line to "- Page X -". 

lines 28-31 

Sets the row header value to read (left- justified and trimmed): 
Employee X is X years old and earns $X 

line 33 

Invokes display, using the sort sequence "state city salary." 
lines 37-225 

System display — notice that the top of each page (lines 37. 101, 165) indicate a 
report by state (ak, az, ca). Additionally, the report is sorted by city, where: 

ak - juneau (line 39) 
az - phoenix (line 103) 

- tucson (line 121) 
ca - fresno (line 167) 

- los angeles (line 185) 

- sacramento (line 207) 

and finally employees are listed in ascending salary order. 
The remaining two pages of the report follow. 
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101 State: az 



103 City: phoenix 



Employee manzo is 74 years old and earns $ 4,200.01 
Employee meadow is 52 years old and earns $ 9,800.01 
Employee meagher is 52 years old and earns $10,500.01 
Employee mcclowsky is 68 years old and earns $10,800.01 
Employee june is 73 years old and earns $10,900.01 
Employee dupuis is 28 years old and earns $12,000.00 
Employee kane is 58 years old and earns $12,300.01 
Employee maclin is 79 years old and earns $12,500.01 
Employee macmahon is 37 years old and earns $12,600.01 
Employee abel 1 is 55 years old and earns $13,000.01 
Employee geist is 21 years old and earns $14,600.01 
Employee lednar is 71 years old and earns $15,000.01 
Employee Corcoran is 38 years old and earns $18,300.01 
Employee bander is 70 years old and earns $21,100.01 
Employee mccoy is 67 years old and earns $31,300.01 



121 City: tucson 



Employee pauley is 56 years old and earns $11,600.01 
Employee monaco is 30 years old and earns $12,300.01 
Employee nevitte is 77 years old and earns $12,300.01 
Employee neubauer is 57 years old and earns $12,400.01 
Employee ordeman is 21 years old and earns $15,200.01 

. ( 33 bl ank 1 i nes ) 

161 - Page 2 - 
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165 State: ca 



167 City: fresno 

Employee jupiter is 47 years old and earns $ 4,100.01 
Employee maclure is 47 years old and earns $ 9,700.01 
Employee kang is 76 years old and earns $10,000.01 
Employee macmannis is 32 years old and earns $10,200.01 
Employee meakin is 51 years old and earns $11,600.01 
Employee george is 44 years old and earns $12,100.01 
Employee costello is 53 years old and earns $12,400.01 
Employee abernathy is 61 years old and earns $12,500.01 
Employee mccrary is 53 years old and earns $12,500.01 
Employee marcey is 71 years old and earns $12,600.01 
Employee monger is 61 years old and earns $12,600.01 
Employee mcclung is 71 years old and earns $13,100.01 
Employee meadoows is 26 years old and earns $14,100.01 
Employee bane is 50 years old and earns $15,200.01 
Employee 1 eel and is 77 years old and earns $32,800.01 

185 City: 1 os angel es 

Employee cowes is 58 years old and earns $ 9,500.01 
Employee newhal 1 is 30 years old and earns $10,000.01 
Employee aboe is 41 years old and earns $10,201.01 
Employee giannoti is 45 years old and earns $10,900.01 
Employee macmillan is 52 years old and earns $11,400.01 
Employee leestma is 69 years old and earns $12,300.01 
Employee katz -is 70 years old and earns $12,400.01 
Employee orf is 70 years old and earns $12,400.01 
Employee marcus is 62 years old and earns $12,600.01 
Employee meagher is 67 years old and earns $12,600.01 
Employee mccory is 54 years old and earns $12,700.01 
Employee justin is 34 years old and earns $12,900.01 
Employee pavlov is 24 years old and earns $14,000.01 
Employee macmahon is 57 years old and earns $14,800.01 
Employee nevitte is 39 years old and earns $14,900.01 
Employee mccormick is 26 years old and earns $15,000.01 
Employee monroe is 42 years old and earns $18,900.01 
Employee mealey is 36 years old and earns $21,600.01 
Employee barker is 78 years old and earns $32,800.01 

207 City: Sacramento 

Employee newman is 68 years old and earns $ 4,200.01 
Employee orlaens is 41 years old and earns $10,300.01 

( 12 data 1 ines) 
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229 ! d i sp 1 ay_emp 1 oyee : q 

230 (Multics command level - ready message) 



This concludes the sample user session. 
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SECTION 3 



SUBROUTINE OVERVIEW AND TUTORIAL 



This section provides an overview of the report_writer_ subroutine, including examples 
organized to provide a tutorial on using the subroutine. The report_writer_ subroutine 
entrypoints are documented in reference material format in Section 5. A PL/I coded example 
that uses report_writer_ is in Section 6. 

Application subsystems that utilize the report writer do so by interfacing through the 
report_writer_ subroutine and the subsystem utilities subroutine (ssu_). The report_writer_ and 
ssu_ provide the necessary subroutine entrypoints for an application subsystem to include the 
report writer with an minimal amount of coding. 

Note: Ref er to the Programmer's Ref erence Manual and the Subroutines Manual f or ssu_ 
reference material and subroutine description. 



CREATING AN INVOCATION 

The application subsystem creates a report writer invocation through the 
report_writer_$create_invocation entrypoint. Prior to creating a report writer invocation, the 
application subsystem must have created an ssu_ invocation through the ssu_$create_invocation 
or ssu_$standalone_invocation entrypoints. All information specific to the application 
subsystem is supplied to the ssu_ and report_writer_ entrypoints. Af ter creating the invocation, 
all of the report writer functions described in Section 1 are available to the application subsystem. 

The application subsystem provides a procedure that does the actual retrieval of data from its 
source data file. This procedure is called the application's "table manager" program, and is called 
by report_writer_ when rows are needed to format the report. The table manager procedure is 
described in detail under "Data Table Retrieval" below. 

The following diagram (Figure 3-1) shows the relationship between the subsystem, 
report_writer_, and the table manager. 
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report_data COMMAND 
I 

i 

ssu_$create_invocation 



The user types a command to invoke a data reporting 
application subsystem. 



The application creates an ssu_ invocation to process 
user requests. 



report_writer_$create_invocation The application creates a report writer invocation. 

i 

t 



ssu_$add_request_table 

i 

I 

ssu_$add_inf o_dir 

i 

ssu_$add_request_table 



ssu_$add_inf o_dir 



The report writer calls ssu_ to define the report writer 
requests which are available within the subsystem. 



The report writer calls ssu_ to define where info 
segments are located for the report writer requests. 



When the report writer returns, the application adds 
the standard ssu_ requests after those of the report 
writer, for use within the application subsystem. 



It also adds the info segments for the standard ssu_ 
requests. 



ssu_$listen 



The application calls the ssu_ listener to read and 
process request lines typed by the user. 



Figure 3-1. Creating an Invocation 

The initial step in using report_writer_ is to call the create_invocation entrypoint. This 
entrypoint takes the name of the table manager procedure f rom the calling Multics subsystem and 
an ssu_ info pointer as input parameters, and passes back a pointer to the report_writer_ specific 
info structure if the invocation can be created. This returned report_writer_ info pointer is saved 
and passed as the first parameter to every report_writer_ entrypoint to uniquely identify this 
specific invocation of report_writer_. If the invocation cannot be created, the code and error 
message parameters supply the reason for the failure to create. The following code fragment 
shows an example usage of this entrypoint 

call report_wr i ter_$create_i nvocat ion ("my_table_manager", 
ssu__i nf o_ptr , report_wr i ter_i nf o_ptr , code, message); 
if code ~= 0 

then call ssu_$abort_l i ne (sci_ptr, code, message); 

If the table manager procedure name parameter is blank, the create_invocation entrypoint 
obtains the name of the subsystem via the ssu_$get_subsystem_name subroutine and uses this for 
the table manager procedure name. 



3-2 



GB63 



This entrypoint calls ssu_$get_info_ptr to obtain the info pointer for the application 
subsystem. It is passed as the first parameter to the table manager procedure in the calling 
subsystem, so that the table manager can access its own info structure and perform operations 
(refer to "Subsystem Table Manager Procedure" below for additional information). 

The report_writer_ also calls ssu_$get_ec_suffix. Any saved report layouts processed by 
save_format_options, or restore_format_options must have the fo.ec_suffix name, Where 
ec_suffix is the suffix returned by ssu_. 



DATA TABLE RETRIEVAL 

The application subsystem provides the selection of a table through its own choice of 
methods. For example, the LINUS subsystem provides the selection of a table through the 
input_query and translate_query requests. 

Before a table has been selected (e.g., by issuing application-provided requests), the requests 
that deal with format options allow references to general report options, but do not allow 
references to general or specific column options. When the application subsystem has selected a 
table, it calls a report_writer_ entrypoint to describe the selected set of columns to the report 
writer, and report_writer_ generates a default report layout based on these column descriptions. 
After calling this entrypoint, the requests that deal with format options allow references to 
general and specific column options. 

Although the data selected by the user can come from several different sources (e.g., from 
several different relations within a MRDS data base), the data that the user eventually sees is 
considered to be a table made up of one or more columns, that must contain at least one row. This 
tabular data that the user sees is the same retrieved data table discussed in Sections 1 and 2. 
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The following diagram (Figure 3-2) shows the relationship between the subsystem, 
report_writer_, and the table manager. 



select REQUEST 



The user types an application-provided request to 
identify the data to be displayed. 



CLOSE FILES 



The select request closes files associated with the 
previous select request. 



OPEN FILES 



Note: 



The select request opens the files containing the data 
just selected. 

Some applications may find it more convenient to open and close files 
in its table manager procedure, at the beginning and end of the data 
retrieval operation. Other applications may find it more convenient to 
open files when the application is first invoked, and close files as the 
application is being terminated. 



repor t_writer_$def ine_columns 



The select request structures the selected data as a 
table. Each row of the table contains one or more 
column values. The select request informs the report 
writer of the name and data type for each column. 



Figure 3-2. Selecting A Table 

The application subsystem provides a table manager procedure that prepares for data 
retrieval, does the actual retrieving of individual rows, and terminates the data retrieval. The 
report writer calls the subsystem's table manager create_table entrypoint when requested to do a 
new retrieval, the delete_table entrypoint when requested to delete the retrieval (via 
display _discard_retrieval), and the get_row entrypoint to retrieve each row of the table during 
the formatting process. After each get_row operation, report_writer_ takes the data returned 
from the table manager procedure and places it into an internal location. The sorting of the 
retrieved data table is done by report_writer_ using its own internal copy. The multi-pass 
formatting, where several passes over the retrieved data table are necessary, is also done by 
report_writer_, on its own internal version of the retrieved data (i.e., the get_row entrypoint is 
only called once for row number 1, regardless of the number of passes over row 1 that are 
necessary to format the report). 

In the case of a subsystem like LINUS, the create_table begins a new data retrieval from 
MRDS, get_row gets a single row through the dsl_$retrieve subroutine, and delete__table 
accomplishes whatever cleanup is necessary after the retrieval is completed. 
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The following diagram (Figure 3-3) shows the relationship between the subsystem, 



report_wnter_, and the table manager. 
set_format_options REQUEST 



t 

display REQUEST 



TABLE_MGR_$create_table 



report_writer_$convert_and_move_row 



The user types a report writer request to 
specify how the selected data should be 
formatted when it is displayed. This includes 
setting page formats as well as column 
formats. 



The user types a report writer request to sort 
and display the selected data. 



The report writer's display request calls an 
application-provided table manager 
entrypoint to setup for retrieving the 
selected table rows, and to retrieve the first 
row. 



The application's table manager calls a report 
writer routine to convert the fields of a table 
row into character strings, storing the 
converted strings in the display request's row 
value buffer. 



+ 



Note: Depending on the application, this call is not always necessary (refer to 
"The Row Value Buffer", "Create_tabie Entrypoint", and "Get_row 
Entrypoint" descriptions below for an alternate way to accomplish this). 



TABLE_MGR_$get_row 



The display request calls the table manager to 
retrieve the remaining rows of the table. 



report_writer_$convert_and_move_row The table manager converts and stores each 

retrieved row into the row buffer. 



DISPLAY ROUTINE 

I 

TABLE_MGR_$delete_table 



The display request then sorts and displays 
the retrieved data. 



The display request calls the table manager to 
clean up after all table rows are retrieved. 



Figure 3-3. Displaying the Data 
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Data Tables 

Reports are created using data which is viewed as a table. The table is made up of one or more 
columns, and contains one or more rows. No table is defined upon invocation of the 
report_writer. The selection of any particular table is done by the application subsystem. Until a 
table is defined, the report_writer_ standard requests do not allow references to any specific or 
general column options and a report cannot be formatted. 



DEFINING A TABLE 

After a table is selected by the application subsystem, its select request calls the 
report_writer_ define_columns entrypoint to inform report_writer_ that a set of columns has 
been selected. After this call, the standard requests allow references to general and specific 
column options, and make possible the formatting of reports. 

The entrypoint is called with the report_writer_ info pointer as the first parameter and a 
pointer to the row_info structure as the second parameter. See "Row Information Structure" 
below for a code fragment initializing this structure and the define_columns entrypoint 
description in Section 5 for a description of the structure. The code and message parameters 
reflect any errors that occur during execution. 

If the def ine_columns entrypoint was previously called with a valid set of columns, and some 
user action results in there being no current set of columns defined, the define_columns 
entrypoint should be called again with a null pointer to the row_info structure. This causes 
report_writer_ to delete its information on the previously defined set of columns. Until this is 
done, repor t_writer_ considers the old set of columns valid. 

The following code fragment illustrates its usage when the application subsystem wishes to 
define a set of columns. 

call report_wr i ter_$def i ne_col umns (report_wr i ter_i nf o_ptr , 

row_i nf o_ptr , code, message); 
if code ~= 0 

then call ssu_$abor t_l i ne (ssu_l nf o_ptr , code, message); 
The next code fragment illustrates its usage when there is no defined set of columns. 

call repor t_wr i ter_$def i ne_col umns (repor t_wr i ter_i nf o_ptr , 

null, code, message); 
if code ~= 0 

then call ssu_$abor t_l i ne (ssu_i nf o_ptr , code, message); 

ROW INFORMATION STRUCTURE 

The row inf ormation structure provides report_writer_ with all of the inf ormation about the 
table needed produce a default report layout, do data conversions, and produce reports. This 
structure is documented in the define_columns entrypoint in Section 5. The calling program 
allocates this structure, sets the version number, and fills in the names and descriptors arrays. All 
other elements of this structure are filled in by the define_columns entrypoint. 

The following code fragment shows a portion of a program that uses MRDS, allocates and 
initializes the row_info structure, and calls report_writer_ to define a set of columns. 

call ds l_$get_attr i bute_l i st (data_base_i ndex, rel at i on_name, 
work_area_ptr , mrds_attr i bute_l i st_structure_vers i on , 
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mrds_attr i bute_l i st_ptr , code); 
if code 0 

then call ssu_$abor t_l i ne (sci_ptr, code, "Getting data base attributes."); 
row_i nf o_i n i t_number_of_ccl umn.s 

= mrds_attr i bute_l i st . num_attrs_i n_v i ew; 
allocate row_info in (work_area) set (row_i nf o_ptr) ; 
row_info. vers ion = ROW_i NF0_VERS 1 0N_1 ; 
do loop = 1 to row_i nf o_i ni t_number_of_col umns; 

row_i nfo.col umn (loop) .names 

= rtrim (mrds_attr ibute__l ist.attr ibute (loop) .mode 1_name) ; 

row_i nfo.col umn (loop) .descriptors 

= mrds_attr ibute_l i st.attr ibute (loop) .user_data_type; 

end ; 

call report_wr i ter_$def i ne_col umns (repor t_wr i ter_i nf o_ptr , 

row_i nf o_ptr , code, message); 
if code ~= 0 

then call ssu_$abor t_l i ne (ssu_i nf o_ptr , code, message); 



Subsystem Table Manager Procedure 

The retrieval of data from the source file is the responsibility of an application provided 
program (called the "table manager" procedure) which is specified when the invocation is created. 
The table manager procedure is called by report_writer_ during the formatting process when data 
to produce the report is needed, and at the beginning and end of the data retrieval process. 

When the invocation is created, report_writer_ tries to find the entrypoints create_table, 
delete_table, get_row, and get_query. The last entrypoint is optional, but the first three 
entrypoints must be present in the table manager procedure or the invocation is not created. 
When the mandatory entrypoints are called by report_writer_, they are passed two parameters. 
The first parameter is the Multics subsystem's info structure pointer which is used by the table 
manager procedure to reference data items in its info structure necessary to perform its function. 
The second parameter is an error code which is used to report any errors back to report_writer_. 
The optional entrypoint is passed these same parameters as the first and last parameters, with the 
same usage. The second and third parameters are filled in by the table manager procedure if 
execution completes successf ully . The second parameter points to the data selection query used to 
select the current table, and the third parameter is the query's length. 



THE ROW VALUE BUFFER 

The row value buffer is the location where the table manager procedure places the row value 
after it is extracted from the source data file. The maximum row value length supported by 
report_writer_ is the number of characters that fit in one Multics segment. When the 
report_writer_$define_columns entrypoint is called with a row_info structure, elements within 
the structure that deal with the row value buffer are filled in by repor t_writer_. The 
row_info.value_ptr is the pointer to the row value buffer, and its length can be found in 
row_info.value_length. The row_info. column array contains the index into the buffer where 
each column value is expected to be found by report_writer_, and the column length. Each 
column within the buffer is treated as a non-varying, unaligned character string. 

The declarations in the include file rw_row_info.incl.pll provide two methods to access 
column values. The include file contains the following declaration for the entire row value: 
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declare row_yalue char (row_i nf o .va 1 ue__l ength) 
based (row_i nf o . va 1 ue_ptr) ; 

The following code fragment uses this declaration and the PL/ 1 substring operation to access the 
column values within the row. 

do loop = 1 to row_i nf o.number_of_columns; 
call i oa_ (" A a", substr (row_value, 
row_i nf o.col umn (1 oop) . i ndexes , 
row__i nf o.col umn (loop) . lengths) ) ; 

end; 

The include file also contains the declarations: 

declare row_va 1 ue_as_an_a rr ay (row_i nf o. va 1 ue_l ength) 
char (1) based (row_i nfo.value_ptr) ; 

declare column_value 

char (row_i nf o. col umn. 1 engths 

(row_i nfo.current_column_number) ) 
based (addr (row_val ue_as_an_array 
(row_i nf o . col umn . i ndexes 

(row_i nf o.current_col umn_number) ) ) ) ; 

The next code fragment uses these declarations to access the column values. 

do row_i nf o.current_col umn_number = 1 to 
row_i nfo.number_of_columns; 
call i oa_ ("~a", col umn_va 1 ue) ; 

end ; 



CREATE J ABLE ENTRY POINT 

The create_table entrypoint of the application's table manager is called by report_writer_ 
when a new set of retrievals are requested. The table manager procedure may open files, perform 
initialization, etc. when this entrypoint is called. It also retrieves the first row from its source 
data file, and moves the row value into the row value buffer. If the source data file contains only 
character data type columns, the values can be moved directly into the row value buffer. If the 
source data file contains other data type columns, the report_writer_ entrypoint 
convert_and_move_row can be called to move the row value into the buffer with data 
conversions. (Refer to "Data Conversions" below for more information on this entrypoint and to 
the "get_row Entrypoint" for additional information on moving a row value into the row value 
buffer without data conversions.) 

If the create_table entrypoint finds the source file empty when retrieving the first row, it sets 
the code to rw_error_$no_data. This is treated as an error by report_writer_, and the setup and 
creation of the report is terminated. The report_writer_ calls ssu_$abort_line with 
rw_error_$no_data, and the user of the application subsystem is provided with the following 
message: 

subsystem (display): No data was found that satisfied the search. 
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GET_ROW ENTRY POINT 

The get_row entrypoint is called by report_writer_ to retrieve a single row from the source 
file and move it into the row value buffer, It is called to retrieve each row except the first row 
(i.e., the first row is returned by the create_table entrypoint). If an end-of-f ile is discovered by 
the table manager procedure when the retrieval of the row is attempted, the code should be set to 
error_table_$end_of _inf o. This indicates a normal end-of-f ile and report_writer_ does not call 
the get_row entrypoint again until a new set of retrievals is requested, via the create_table 
entrypoint. 

The following code fragment shows an example of a structured file containing fixed position, 
unaligned non-varying character data type columns. The record is read directly into the row 
value buffer because it is identical to what report_writer_ is expecting. 

caH i ox_$read_record (iocb_ptr, row_i nf o .va 1 ue_ptr , 

row_i nf o. va 1 ue_l ength, (0), code_parameter) ; 
return; 

The next code fragment shows an example of a structured file containing fixed position 
character data type columns, which are a mixture of varying, non-varying, aligned, and 
unaligned. The record is read into the structure, and is moved into the row value buffer to end up 
with unaligned, non-varying column values placed in their correct positions within the row value 
buffer. 

declare 1 employee aligned, 

2 number char (8) varying, 

2 street char (6^) varying, 

2 city char (32) varying, 

2 state char (2) unaligned, 

2 zip_code char (5) unaligned; 
call i ox_$read_record (iocb_ptr, addr (employee), 

currentsize (employee) * k> (0) , code_parameter) ; 
if code_parameter ^= 0 
then return; 

row_i nf o.current_col umn_number = 1; 
column_value = employee. number; 
row_i nfo.current_coiumn_number = 2; 
column_value = employee. street; 
row_i nfo.current_column_number = 3; 
col umn_va 1 ue = employee.c i ty ; 
row_i nf o.current_col umn_number = h; 
column_value = empl oyee. state; 
row_i nf o.current_col umn_number = 5; 
co1umn_value = empl oyee. z i p_code; 



DELETE J ABLE ENTRYPOINT 

The delete_table entrypoint is called by report_writer_ when the processing of the report is 
completed. The table manager procedure may close open files, free allocated variables, etc. when 
this entrypoint is called. 
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GET_QUERY ENTRY POINT 

The get_query entrypoint is called by report_writer_ when the report_writer_ 
save_format_options request is invoked with the -query control argument. This specifies to 
save_f ormat_options that the data selection requests should be saved along with the report layout. 

This entrypoint is optional, and if not found in the table manager procedure when the 
report_writer_ invocation is created, the save_f ormat_options request calls ssu_$abort_line with 
the code error_table_$unsupported_operation. 

The data selection requests are dependent on the application subsystem, and should contain 
whatever subsystem requests are necessary to reselect the current table. The requests are saved in 
a subsystem exec_com, along with other requests that set the current report f ormat. A subsequent 
restore_format_options request invokes the exec_.com and executes these requests to reselect the 
table and restore the current report format. An example of a query specific to the LINUS 
subsystem is: 

input_query -force -brief -termi nal_i nput 
select * from employee 

trans late_query 

If any ampersands are found within the query that would be interpreted by exec_com when 
the report layout is restored, they are protected by save_format_options with double ampersands 
before being placed in the saved report layout file. In the case of a subsystem like LINUS, a 
portion of a select statement that looked like: 

& name = "Smith" 

would be saved as: 

&& name = "Smith" 

The save_format_options request also provides an exec_.com & version statement and 
&attach input lines statement, placed prior to the query and format option request lines. 

The entrypoint is called with the calling subsystem info structure pointer as the first 
parameter. The second parameter is a pointer to a segment where the table manager procedure 
places the query. The third parameter is f or the length of the query in characters, and is set by the 
table manager procedure. The fourth parameter is a standard error code, and is set to zero if the 
get_query entrypoint succeeds. If the get_query entrypoint fails, it sets this parameter to a 
standard error code to indicate the reason for the failure. 



Data Conversions 

The report_writer_ convert_and_move_row entrypoint can be called by the table manager 
procedure to have values converted from the original source file data types, to non-varying, 
unaligned character strings. The converted values are moved into the row value buffer as part of 
the conversion process. 

The following code fragment shows how a record from a structured file can be placed in the 
row_value buffer when the record contains a mixture of data types. The record is read into a 
structure, an array of pointers is set to point to the structure elements that make up the column 
values in column order, and the convert_and_move_row entrypoint is called to perform data 
conversions and place the converted column values into their correct positions within the row 
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value buffer. In the example, the column order is, employee.number, employ ee.assignment, 
employee.salary, and employee.age. 

declare 1 employee aligned. 

2 number char (8) varying, 

2 salary fixed dec (7,2) unaligned, 

2 age fixed dec (2) unaligned, 

2 assignment fixed bin; 
declare va 1 ue_ptrs (h) ptr; 

call iox_$read_record (iocb_ptr, addr (employee), 

currentsize (employee) * k, (0) , code__parameter) ; 
if code_parameter ~= 0 
then return; 

value_ptrs (1) = addr (employee.number) ; ■ 
value_ptrs (2) = addr (employee. ass i gnment) ; 
value_ptrs (3) = addr (employee.salary); 
value_ptrs {h) = addr (employee.age) ; 
cal 1 report_wr i ter_$conver t_and_move_row 
(repor t_wr i ter__i nf o_ptr , value_ptrs) ; 

Note that in some cases, the table manager might use only a few of the structure elements as 
table columns, or might read records from two or more data files and merge them into a single 
table row, with columns coming from several data files. 



REPORT PREPARATION 

A default report layout is provided for each selected set of columns as described in Sections 1 
and 2. The listing of formatting options is done through the list_format_options request 
described in Sections 1, 2, and 4. If the appliction subsystem provides a request level interface, 
the user can type the list_f ormat_options request. If the application subsystem does not provide a 
request level interface, it must utilize the ssu_$evaluate_active_string entrypoint to obtain the 
value of a format option. The restore_format_options, save_format_options, and 
set_format_options requests can be invoked in the application when a user types these requests, 
or the application can use ssu_$execute_string or ssu_$execute_line to invoke these requests on 
the user's behalf. 



REPORT FORMATTING 

The display, display_builtins, and column_value requests provide for the formatting of a 
report. The display request is invoked in the user typing display, or the application subsystem 
calling the ssu_$execute_line or ssu_$execute_string to invoke these requests on the user's behalf. 
The display _buil tins and column_value requests are normally accessed by including references to 
them in the values of format options which are set through the set_format_options request, but 
can also be accessed during report creation by the application subsystem through the 
ssu_$evaluate_active_string entrypoint. 



DESTROYING AN INVOCATION 

The application subsystem destroys a report writer invocation with the 
report_writer_$destroy_invocation entrypoint. 
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The following diagram (Figure 3-4) shows the relationship between the subsystem, 
report_writer_, and the table manager. 



quit REQUEST The user types the standard ssu_ quit request to exit 

| the application. 

I 

ssu_$listen The quit request causes the ssu_ request line listener to 

| return to the main procedure of the application. 

I 

report_writer_$destroy_invocation The application calls to destroy the report writer 

invocation. 

ssu_$destroy_invocation The application calls to destroy the ssu_ invocation. 

CLOSE FILES The application closes files associated with the final 

set of selected data. 



Figure 3-4. Destroying an Invocation 



The last step in using report_writer_ is to call the destroy _invocation entrypoint. This 
entrypoint takes the report_writer_ info pointer as its only parameter. If the pointer is null, the 
call is ignored. The following code fragment illustrates its usage. 

ca 1 1 repor t_wr i ter_$destroy_i nvocat i on (report_wr i ter_i nf o_ptr) ; 
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SECTION 4 



REPORT WRITER REQUEST DESCRIPTIONS 



This section contains a description of the MRW requests. Each request description contains 
the name (including the abbreviated form, if any), discusses its purpose, and shows correct usage. 
Notes and examples are included where necessary for clarity. 

The following list summarizes the MRW requests. 
column_value, civ 

returns the value of the specified column for the current row, previous row, or next 
row. 

display, di 

retrieves selected data, creates a report, and displays the information or writes it to a 
file. 

display_builtins, dib 

returns the current values for requested built-ins. 

list_format_options, lsfo 

lists the names and values of format options. 

restore_format_options, rsfo 

restores saved report layouts. 

save_format_options, svfo 

saves current values of format options for future use. 

set_format_options, sfo 

changes/sets report format options. 

The remainder of this section contains a detailed description of each request. 
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column value 



column value 



Request: column value, civ 

This request returns the value of the specified column for the current row, previous row, or 
next row. It can only be used as an active request. It is used within a formatted report produced 
by the display request to obtain the value of a column. It is an error to use this request anywhere 
except in a header /footer or editing string within a report produced by the display request. 



USAGE AS AN ACTIVE REQUEST 

[civ column_id {-control_args} ] 



where: 

1. column_id 

specifies which column value is to be returned. It can be given as the name of the 
column or the number of the column as selected through the subsystem. 

2. control_args 

can be chosen from the following: 

VUX 1 Wil I 1 V/ TT , Wl TV 

returns the value of the named column for the current row. (Default) 
-default STR 

returns the character string STR when there is no previous row, or when there is no 
next row. (Default value for STR is "" if this control argument is not provided.) 

-next_row, -nrw 

returns the value of the named column for the next row. If there is no next row, the 
string "" is returned unless changed by the -default control argument. 

-previous_row, -prw 

returns the value of the named column for the previous row. If there is no previous 
row, the string "" is returned unless changed by the -default control argument 



NOTE 

When a subtotal is being generated, the column_value request returns the value of the 
subtotal, rather than the value of the column. An editing string for a column like " [pic $99v.99 
[civ salary] ] ", would edit the value of the salary column through the picture active request for 
every row. When a subtotal is being generated, the value of the salary subtotal is edited through 
the picture active request. This behavior also applies to subcounts, counts, and totals, in addition 
to subtotals. 



EXAMPLES 
[civ foo] 

[civ 31 
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column value display 

[civ foo -previ ous_row] 

[civ foo -next_row -default NULL] 



Request: display, di 

This request retrieves selected data, creates a report, and displays it on the terminal or sends it 
to a file or an io switch. 



USAGE 

di {-control_args} 



where control_args can be chosen from: 

Note: The following list identifies all control arguments grouped by function. 



CONTROLLING WARNING MESSAGES 
-brief 
-long 

DISPLAYING PAGES AND PORTIONS OF PAGES 
-all 

-character_positions 
-page 

DATA RETRIEVAL INITIATION AND TERMINATION 
-discard_retrieval 
-keep_retrieval 
-new_retrieval 
-old_retrieval 



REPORT INITIATION AND TERMINATION 
-discard_report 
-keep_report 
-new_report 
-old_report 

SOP-TING RETRIEVED DATA 
-sort 



CONTROLLING REPORT OUTPUT 
-extend 
-output_file 
-output_switch 
-truncate 
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display 



display 



VIDEO SYSTEM SCROLLING FUNCTIONS 
-enable_escape_keys 
-enable_f unctionjceys 
-scroll 
-set_key 
-window 

MULTI-PASS REPORT FORMATTING 
-passes 

TEMPORARY STORAGE SPECIFICATION 
-temp_dir 



displays all pages of the report. This argument is incompatible with the -pages 
control argument. (Default) 

-brief, -bf 

suppresses warning messages. 

-character_positions STR1 {STR2}, -chpsn STR1 {STR2} 

where STR1 and STR2 define the left and right character positions of a vertical 
section of the report. STR1 must be given and defines the left margin position to 
begin from. STR2 is optional, and if not given, defaults to the rightmost character 
position of the report. If this control argument is not given, the entire page is 
displayed. 

-discard_report, -dsrp 

deletes the report on termination. (Default) 

-discard_retrieval, -dsr 

deletes retrieved data on termination. (Default) 

-enable_escape_keys, -eek 

specifies the use of escape key sequences, rather than the function keys and arrow 
keys on the terminal, for scrolling functions. This is the default if the -scroll 
control argument is given and the terminal does not have the necessary set of 
function keys and arrow keys (see -enable_function_keys). (In the following 
description, the mnemonic "esc-" means the escape key on the terminal.) The 
following escape key sequences are used if this control argument is given, or the 
terminal lacks the necessary set of keys: 



-all, -a 



FUNCTION NAME 



KEY SEQUENCE 



forward 
backward 
left 
r i ght 
hel p 
set_key 

set_scrol l_increment 
qu i t 

red i spl ay 



esc-f 
esc-b 
esc- 1 
esc-r 



esc-? 
esc-k 



esc- 1 



esc-q 
esc-d 
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display 



display 



start_of_report esc-s 

snd of report ssc - s 

mul tics_mode esc-m 

goto esc-g 

-enable_function_keys, -efk 

specifies the use of terminal function keys and arrow keys for scrolling functions. 
This is the default when the -scroll control argument is given and the terminal has at 
least nine function keys and four arrow keys. (In the following description, the 
mnemonic fN means function key N, where N is the number of the function key. 
The mnemonic down_arrow means the down arrow key, up_arrow means the up 
arrow key, lef t_arrow means the lef t arrow key, and right_arrow means the right 
arrow key. The following key sequences are used if this control argument is given 
and the terminal has the necessary set of keys: 

FUNCTION NAME KEY SEQUENCE 

forward down_arrow 

backward up_arrow 

left left_arrow 

right right_arrow 

help fl (function key) 

set_key f2 

set_scrol l_i ncrement f3 

quit fk 

redisplay f5 

start_of_report f6 

end_of_report f] 

multics_mode f8 

goto f 3 



-extend 

appends the report to an existing file rather than replacing it if the -output_file 
control argument is used. (Default is to truncate an existing file if this control 
argument is not provided.) 

-keep_report, -krp 

keeps the report on termination. This control argument is necessary in order to use 
-old_report on subsequent invocations of display. 

-keep_retrieval, -kr 

keeps retrieved data to allow re-use on subsequent invocations of the display 
request. Previously retrieved sorted data retains the sort order. 

-long, -ig 

displays warning messages when a control argument such as -old_retrieval is used 
and the data from a previous retrieval is not available. (Default) 



-new_report, -nrp 

creates a new report (Default) 

-new_retrieval, -nr 

begins a new retrieval. (Default) 
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display 



display 



-old_report, -orp 

uses the report created in the previous invocation. Use of this control argument 
requires that -keep_report be used in the prior invocation of display. 

-old_retrieval, -or 

uses data retrieved during the previous invocation. Use of this control argument 
requires that -keep_retrieval be used in the prior invocation of display. 

-output_file path, -of path 

where path is the name of the file which contains the formatted report. If this 
control argument or -output_switch is not given, the report is displayed on the 
terminal. This argument is incompatible with the -output_switch control argument. 

-output_switch switch_name, -osw switch_name 

where switch_name is the name of a switch to be used to display the report. If this 
control argument or -output_file is not given, the report is displayed on the 
terminal. It is an error to use this control argument if the named switch is not 
already open and attached when display is invoked. This argument is incompatible 
with the -output_file control argument. 

-page STR, -pg STR; -pages STR, -pgs STR 

where STR is a blank-separated list of pages (N N) or comma-separated page ranges 
where STR is a blank-separated list of pages (N N) or comma-separated page ranges 
(N,N). Page ranges can also be given as N, or "N,$" which means from page N to the 
end of the report, or simply $ which means the last page. This argument is 
incompatible with the -all control argument. 

-passes N, -pass N 

where N is the number of times the report is to be f ormatted. No output is produced 
until the last formatting pass of the report. (Default value for N is 1) 

-scroll 

specifies scrolling the report according to key sequences read from the terminal. 
Only terminals supported by the Multics video system can use the scrolling feature. 
If the -window control argument is not used, the -scroll argument creates a 
uniquely named window for the display of the report. The user_i/o window is 
reduced to four lines and the remaining lines are used for the uniquely named report 
display window. The minimum size for this window is five lines, so the user_i/o 
window must be at least nine lines before invoking display, unless the -window 
control argument is used. 

-set_key STR, -sk STR; -set_keys STR, -sks STR 

specifies that the named scrolling functions are to be set to the provided key 
sequences. STR is a blank-separated list of one or more scrolling function names 
and key sequences, given as: 

f unct i on_name key_sequence ... {f unct i on_name key-sequence} 

The function names can be chosen from the set described under 
-enable_escape_keys or -enable_function_keys control arguments. The key 
sequences can be given as the actual sequences or mnemonic key sequences. The 
provided mnemonics can be: 
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display 



display 



fN 



esc= or escape- 



where N is the number of the desired 
function key 

corresponds to the escape character 



ctl-x or control -x correspods to the character sequence 

generated when the control key is held 
while also pressing the character 
named by "x" 



down_ar row 
up_arrow 
1 ef t_ar row 
home 



corresponds to the down arrow key 
corresponds to the up arrow key 
corresponds to the right arrow key 
corresponds to the home key 



-sort STRs {-ascending j -descending} {-case_sensitive | 

-non_case_sensitive), -sort STRs {asc | -dsc} -cs | -ncs} 
where STRs are the names of columms or numbers corresponding to the position of 
the columns as selected through the subsystem. It can be followed by -ascending or 
-descending, and -case_sensitive or -non_case_sensitive. (Default is -ascending 
and -case_sensitive.) 

-temp_dir dir_name, -td dir_name 

specifies that the given directory be used for storing the retrieved data, saving the 
report if -keep_report is used, and sorting workspace if -sort is used instead of the 
process directory. This temporary directory continues to be used until another new 
temporary directory is requested. A new temporary directory can only be specified 
when a new retrieval and new report are requested. 

-truncate, -tc 

replaces the contents of the existing file if the -output_file control argument is 
used. (Default is to truncate if the -extend control argument is not provided., 

-window STR, -win STR 

specifies that the window named by STR be used for the display of the report. This 
argument is only meaningf ul when the -scroll argument is also used. If this control 
argument is used, the window named by STR must be attached and open under the 
video system, and it must be at least five lines high. 

EXAMPLES 
di 

d i -output_f i 1 e f oo 

di -keep_retr ieval -sort bar -descending 
di -keep_retr i eva 1 -keep_report -of fool 



-non_case_sens i t i ve 
-character_pos i t i ons 1 132 
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display display builtins 

di -old_retr i eva 1 -old_report -of foo2 -character_pos i t i ons 133 260 

di -pages 1 3 12,19 58,$ -output_swi tch foo 

di -sort foo -descending bar -non_case_sens i t i ve 



Request: display builtins, dib 

This request returns the current value of the built-in named by STR. It can only be used as an 
active request. It is used within a formatted report produced by the display request to obtain the 
current value of the specified built-in. It is an error to use this request anywhere except in a 
header /footer or editing string within a report produced by the display request. 



USAGE AS AN ACTIVE REQUEST 
[dib STR] 



where SiR can be any one of the following built-ins: 

curren t_pass_number 

the number of the current pass. The number begins with 1 and is incremented by 1 
for each additional formatting pass over the report. 

current_row_number 

the number of the current row of the report. 

first_row 

true if the current row is the first row of the report, or false if it is not the first row 
of the report. 

last_page_number 

the number of the last page of the report, or "0" if it is the first pass over the report. 
- After each formatting pass, the number is updated with the number of the last page. 

last_pass 

true if this is the last formatting pass of the report, or false if this is not the last pass 
of the report 

last_row 

true if the current row is the last row of the report, or false if the current row is not 
the last row of the report 

last_row_number 

the number of the last row of the table, or "0" if it is the first pass over the report. 
After the first formatting pass the number is set to the number of the last row, 

page_number 

the number of the current page of the report. 
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previously _processed_row 

true if the current row was processed on the preceding page but the row value would 
not fit and had to be deferred to the current page, or false if this is the first time the 
current row is being processed. 



Request: list format options, lsfo 

This request lists the names and values of individual report formatting options, all report 
formatting options, or the active report formatting options. As an active request, it returns the 
value of the single specified format option. 



USAGE 

lsfo -control_arg -OR- lsfo -f ormat_opt i on_args 



USAGE AS AN ACTIVE REQUEST 
[lsfo -f ormat_opt i on_arg] 



where: 

1. control_args 

can be chosen from the following: 

-active, -act 

specifies that only the active formatting options are to be listed. (Default) "help 
formatting_options.gi" is typed for more information on active formatting options. 
This control argument is incompatible with -all and the format option arguments. 
If -active and -all are both given, the last one supplied is used. 

-all, -a 

specifies that all formatting options are to be listed. This control argument is 
incompatible with -active and the format option arguments. If -all and -active are 
both given, the last one supplied is used. 

2. format_option_args 

can be one or more of the following: 

GENERAL REPORT OPTIONS 
-delimiter, -dm 

displays the character used to delimit the different portions of a header or footer. 

-f ormat_document_controls, -f dc 

displays the interpretation of embedded format document controls when filling 
(on), or the treatment of embedded controls as ordinary text (off). 
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-hyphenation, -hph 

displays hyphenation where possible for overlength values (on), or no hyphenation 
(off). 

-page_footer_value, -pfv 

displays the page footer placed at the bottom of each page. 

-page_header_value, -phv 

displays the page header placed at the top of each page. 

-page_length, -pi 

displays the length of each formatted page given as the number of lines. 
-page_width, -pw 

displays the width of each formatted page given as the number of character 
positions. 

-title_line, -tl 

displays printing of the title line (on) or the suppression of the title line (off), 
-truncation, -tc 

displays the character or characters used to indicate truncation. 

GENERAL COLUMN OPTIONS 

-column_order. -co 

displays the order of columns in the detail line. 

-count, -ct 

displays the columns which have counts taken on them, 
-exclude, -ex 

displays the columns to be excluded in the detail line, 
-group, -gr 

displays the columns used to group a number of rows based on their values. 

-group_f ooter_trigger, -gf t 

displays the columns which can cause the generation of the group footer. 

-group_footer_value, -gfv 

displays the group footer placed after each group of rows. 

-group_header_trigger, -ght 

displays the columns which can cause the generation of the group header. 

-group_header_value, -ghv 

displays the group header placed before each group of rows. 

-outline, -out 

displays the columns which can duplicate suppression. 
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list f ormat options 



=page_break, -pb 

displays the columns which can cause a break to a new page. 

-row = footer_value, -rfv 

displays the row footer placed after each row value. 

-row_header_value, -rhv 

displays the row header placed before each row value. 

-suhcount, -set 

displays the columns that have subcounts taken on them. 

-subtotal, -stt 

displays the columns that have subtotals taken on them, 
-total, -tt 

displays the columns that have totals taken on them. 



SPECIFIC COLUMN OPTIONS 

In the following descriptions, column_id means the column name, the number of the 
column selected through the subsystem, or a star name which is matched against the column 
names. 

-alignment column_id, -al column_id 

displays the alignment mode within the display width for the specified column. 

-editing column_id, -ed column_id 

displays the editing string for the specified column. 

-folding column_id, -fold column_id 

displays the folding action taken when the column value exceeds the display width 
for the specified column. 

-separator column_id, sep column_id 

displays the character string that separates the specified column from the column in 
the detail line which immediately follows it. 

-title column_id, -ttl column_id 

displays the character string that is placed at the top of the page above the specified 
column. 

-width column_id, -wid column_id 

displays the display width in the detail line for the specified column. 



NOTES 

Refer to the description of the set_format_options request for a complete list of the 
default values for the format options and a discussion of their allowed values. When used as an 
active request, only one format_option_arg can be specified. 
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format_options list f ormat_options 

EXAMPLES 
lsfo 

Isfo -all 

lsfo -width 1 -alignment salary 

lsfo -page_width -title ** -page_length 
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Request: restore form adoptions, rsfo 

This request restores the saved report layout specified by path. Only the formatting options 
found in the saved report layout have their values changed. 



USAGE 

rsfo path 

where path is the pathname of the saved report format to be restored. If path does not contain an 
fo.ec_name suffix, one is assumed. The ec_name is specific to the subsystem which is using the 
report writer, and the ec suffix for the subsystem is substituted here by the report writer. 



NOTES 

Refer to the save_format_options request for detail on the content of the saved report 
format. 



EXAMPLES 

rsfo samp 1 e_d i spl ay_f ormat 

rsfo another_d i spl ay_f ormat .fo. lec 



Request: save format options, svfo 

This request saves the current values of f ormat options as a subsystem exec com. The saved 
format can be restored with the restore_format_options request. The file is saved by utilizing a 
suffix of fo.ec_name where ec_name is substituted by the subsystem's ec suffix by the report 
writer. Individual format options, active format options, or all of the format options can be 
saved. The requests used to select the set of columns through the subsystem can also be saved. 



USAGE 

svfo path {-f ormat_opt i on_args} {-control_args} 



where: 

1. path is the pathname of the segment that contains the saved format. If path does not 

have an fo.ec_name suffix, one is assumed. 

2. format_option_args 

refer to the set_format_options request for a complete description of the format 
option arguments. Each format option named has its value saved in the exec_com 
specified by path. These arguments are incompatible with the -all and -active 
control arguments. 
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GENERAL REPORT OPTIONS 
-delimiter, -dm 

-format_document_controls, -fdc 
-hyphenation, -hph 
-page_footer_value, -pfv 
-page_header_value, -phv 
-page_length, -pi 
-page_width, -pw 
-title_line, -tl 
-truncation, -tc 

GENERAL COLUMN OPTIONS 

-column_order, -co 
-count, -ct 
-exclude, -ex 
-group, -gr 

-group_f ooter_trigger , -gf t 
-group_footer_value, -gfv 
-group_header_trigger, -ght 
-group_header_value, -ghv 
-outline, -out 
~page_break, -pb 
-row_footer_value, -rfv 
-row_header_value, -rhv 
-subcount, -set 
-subtotal, -stt 
-total, -tt 

SPECIFIC COLUMN OPTIONS 

-alignment, -al 
-editing, -ed 
-folding, -fold 
-separator, -sep 
-title, -ttl 
-width, -wid 

3. control_args 

can be one or more of the following: 

-active, -act 

specifies that only the active formatting options are to be saved. (Default) "help 
formatting_options.gi" is typed for more information on active formatting options. 
This control argument is incompatible with the format option arguments and the 
-all control argument. If -active and -all are given, the last one supplied is used. 
(Default) 

-all, -a 

specifies that all formatting options are to be saved. This control argument is 
incompatible with the format option arguments and the -active control argument. 
If -all and -active are given, the last one supplied is used. 
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-query 



specifies that the subsystem query request used to select the columns is to be saved. 
A restore_format__options on the saved format also restores and makes the saved 
query current. 



EXAMPLES 

svfo report_l ayout 

svfo report_l ayout -all 

svfo report_l ayout -query 

svfo repor t_ 1 ayout -page_header_va 1 ue -page_f ooter_va 1 ue 

svfo report_l ayout -page_header_val ue -width salary 

svfo repor t_l ayout -width «« -page_f ooter_va 1 ue 



Request: set format options, sfo 

This request sets individual report format options to user -specified or default values, and /or 
all formatting options to default values. 



sfo {-f ormat_opt i on_args} {-control_args} 



Note: The option value given for any format option argument can be the control 
arguments -default or -prompt. If -default is given for the value, report 
writer sets the value of the format option to the system default. If -prompt is 
given for the value, report writer prompts for the value with the prompt string 
"Enter FORM AT_OPTION_N AME. ". A line consisting of the single character 
"." terminates the prompted input mode. To suppress display of the prompt 
string, use the -brief control argument. 



can be one or more of the following: 

GENERAL REPORT OPTIONS 

-delimiter CHAR, -dm CHAR 

CHAR is the character used to delimit the different portions of a header or footer 
and can be set to any printable character. (Default value for CHAR is !) 



USAGE 



where: 
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-format_document_controls STR, -fdc STR 

STR determines if the format_document_ subroutine is to interpret format 
document control lines when filling overlength text. STR can be set to on, meaning 
format_document_ interprets control lines in the text and provides special filling 
actions based on the embedded control lines. (Default value for STR is off, meaning 
format_document_ does not check for control lines embedded in text.) 

-hyphenation STR, -hph STR 

the value of -hyphenation determines if hyphenation is to be attempted when filling 
overlength character strings. STR can be set to "on," specifying that hyphenation is 
to be attempted. (Default value for STR is off, meaning no hyphenation is 
attempted.) 

-page_footer_value STR, -pfv STR 

STR is the page footer placed at the bottom of each page. The page footer can 
consist of more than one line, and each line can have a left, right, and center 
portion. The individual portions of each line are delimited by the delimiter 
character. Active requests found in the footer are evaluated and their return value 
is placed into the footer before folding and alignment takes place. Portions of a 
footer with zero length have their space on the page redistributed to the other 
portions whose lengths are not zero. For example, if the page footer contained only 
a center portion: 

MSample Center Portion!! 

the text is centered on the page and has the full page width available for the text. 
Similarly, a lef t portion or right portion only is aligned to the lef t or right of the 
page and has the full page width available for placement of text. Two exceptions to 
this action are when the footer has a left, right, and center portion, and the left or 
right portion has a zero length, such as: 

! 1 ef t part ! center part!! 

or 

Mcenter part!right part! 

in which case the left or right part of the page is unavailable for placement of text 
(i.e., the space is not redistributed to the other two portions). If the redistribution 
of the available page width is not desired, the placement of a single blank into a 
portion such as "!<SP>!Center Part!<SP>!" prevents the redistribution from taking 
place because each portion has a length greater than zero. (Default value for STR is 
"", meaning there is no page footer provided by default.) 

-page_header_value STR, -phv STR 

STR is the page header placed at the top of each page. Refer to the description of 
-page_footer_value for the content of a header. (Default value for STR is "", 
meaning there is no page header provided by default.) 

-page_length N, -pi N 

N is the length of each formatted page given as number of lines. N can be given as 
"0" or any positive integer. 0 means the report is not to be paginated and is created 
as one continuous stream. (Default value for N is 0) 



4-16 



GB63-00 



format options 



set f ormat__options 



-page_width N, -pw N 

N is the width of each formatted page given as the number of character positions. N 
can be given as "0" or any positive integer. 0 means the page_width is always set by 
report writer to be the exact width needed to contain all of the columns specified in 
the query. If N is greater than zero and the width for any column exceeds N, the 
width of the column is automatically set to N. (Default value for N is 79) 

-titlejine STR, -tl STR 

STR determines if a title line is to be printed. STR can be set to "off" to inhibit the 
printing of the title line. (Default value of STR is on, meaning a title line is printed 
at the top of each page.) 

-truncation STR, -tc STR 

STR determines the character(s) to be used to indicate truncation of some value. 
STR can be set to any sequence of printable characters. (Default value for STR is *) 



GENERAL COLUMN OPTIONS 

-column_order column_list, -co column_list 

columnjist determines the order in which columns appear in the detail line. 
column_list can be set to a list of column names or numbers. Columns missing from 
this list are placed after the columns which appear in the list. That is, if five 
columns were selected and the column_order value is given as "3 2", the complete 
order would be "3 2 1 4 5". (Default value for column_list is the list of columns 
from the query, in the order supplied, meaning that the columns appear in the exact 
order as they appear in the query.) 

-count column_list, -ct column_list 

column_Iist determines the columns for which counts are generated. column_iist 
can be set to a list of column names or numbers. Counts are generated after the last 
detail line. If a count is requested on a column that is excluded, the count is also 
excluded from the page. An exception to this rule is when all columns are excluded. 
Counts are provided in this case to allow reports consisting of some combination of 
counts, subcounts, totals, and subtotals only. (Default value for column_list is "", 
meaning no columns have counts generated.) 

-exclude column_list, -ex columnjist 

column_list determines if any of the columns selected in the query are excluded 
from the detail line. column_list can be set to a list of column names or numbers. 
(Default value for column_list is "", meaning no columns are excluded.) 

-group columnjist, -gr columnjist 

columnjist determines the grouping of a number of rows based on the values of one 
or more columns, columnjist can be set to a list of column names or numbers. The 
column or columns named in the list become a hierarchy of columns. The first 
column named is the major column, and the last column named becomes the minor 
column. The hierarchy of columns can be used with the outline, page_break, and 
subtotal options described below. (Default value for columnjist is "", meaning no 
group of rows is defined.) 

-group_footer_trigger columnjist, -gft columnjist 

columnjist determines when to generate the group footer, columnjist can be set 
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to a list of column names or numbers. The columns which appear in this list must 
also appear in the column list associated with the -group option. If the -group 
option is set to a new value, columns which are eliminated from the column_list are 
also eliminated from the -group_footer_trigger column_list When any of the 
columns specified in the column_list are about to change with the next row, the 
group footer is evaluated. The group footer is always evaluated af ter the last row of 
the report. (Default value for column_list is "", meaning no group footer triggers 
are defined.) 

-group_footer_value STR, -gfv STR 

STR is the group footer placed after each group of rows when any of the columns 
associated with the -group_f ooter_trigger option changes. Refer to the description 
of -page_footer_value above for the content of a header /footer. (Default value 
for STR is "", meaning there is no group footer defined.) 

-group_header_trigger column_list, -grit column_list 

column_list determines when to generate the group header. column_list can be set 
to a list of column names or numbers. The columns which appear in this list must 
also appear in the column list associated with the -group option. If the -group 
option is set to a new value, columns which are eliminated from the column_list are 
also eliminated from the -group_header_trigger column_list. When any of the 

columns specified in the column list have just changed with the current row, the 

group header is evaluated. The group header is always evaluated bef ore the f irst row 
of the report. (Default value for column_list is "", meaning no group header 
triggers are defined.) 

-group_header_value STR, -ghv STR 

STR is the group header placed before each group of rows when any of the columns 
associated with the -group_header_trigger option changes. Refer to the description 
of -page_footer_value above for the content of a header /footer. (Default value 
for STR is "", meaning there is no group header defined.) 

-outline column_list, -out column_list 

column_list determines if duplicate values in a column are to be suppressed. 
column_list can be set to a list of column names or numbers. If the value of a named 
column is the same as its previous value, then the value is suppressed unless it is the 
first line of a new page. (Default value for column_list is "", meaning no columns 
have duplicate values suppressed.) 

If any of the named columns are a member of the "group" of rows defined by the 
group option, then it, and all of the columns more major in this group, are outlined. 
A change in value of any one column displays all columns lower in the hierarchy in 
addition to the column that changed. An exception is the first line on a new page, in 
which case duplicate values are never suppressed. 

-page_break column_list, -pb column_list 

column_list determines when page breaks are generated. column_list can be set to a 
list of column names or numbers. The columns specified in the list are examined, 
and when their values change, a new page break is generated. If any of the named 
columns are a member of the "group" of rows defined via the group option, then it, 
and all columns more major in the group, are examined for page breaks. (Default 
value f or coiumn_list is "", meaning that no columns are examined for page breaks.) 
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-row_footer_value STR, -rfv STR 

STR is the row footer placed after each detail line. Refer to the description of 
-page_footer_value (above) for the content of a footer. (Default value for STR is 
meaning that no row footer is provided.) 

-row_header_value STR, -rhv STR 

STR is the row header placed before each detail line. Refer to the description of 
-page_footer_value (above) for the content of a header. (Default value for STR is 
"", meaning that no row header is provided.) 

-subcount subcount_spec, -set subcount_spec 

subcount_spec determines what columns subcounts to generate, when they should 
be generated, and what type of subcount is generated. (Default value for 
subcount_spec is "", meaning that no subcounts are generated for any columns.) 

subcount_spec can consist of one or more blank-separated "triplets." The syntax of 
a triplet is: 

col umn_l , col umn_2 {reset j running} 
where: 
column_l 

is the name or number of the column for which a subcount is generated. 
column_2 

is the name or number of a column whose value is examined to determine when 
to generate the subcount. When the value of the column being examined 
changes, the subcount is generated. If this column is a member of the group of 
rows defined via the group option, it, and all columns more major in the group, 
are examined for subcount generation. 

reset | running 

indicates the type of subcount desired. If reset is selected, the subcount counter 
is reset to 0 each time a subcount is generated. If running is selected, the 
subcount is not reset to 0. If a subcount is requested on a column that is 
excluded, the subcount is also excluded from the page. An exception to this rule 
is when all columns are excluded. Subcounts are provided in this case to allow 
reports consisting of some combination of counts, subcounts, totals, and 
subtotals only. (Default is reset) 

-subtotal subtotal_spec, -stt subtotal_spec 

subtotal_spec determines what column subtotals to generate, when they should be 
generated, and what type of subtotal is generated, (Default value for subtotal_spec 
is "", meaning -no subtotals are generated for any columns.) 

subtotal_spec can consist of one or more blank-separated triplets. The syntax of a 
triplet is: 

column_l , col umn_2{, reset | running} 
where: 
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column_l 

is the name or number of the column for which a subtotal is generated. 
column_2 

is the name or number of a column whose value is examined to determine when 
to generate the subtotal. When the value of the column being examined 
changes, the subtotal is generated. If this column is a member of the group of 
rows defined via the group option, it, and all columns more major in the group, 
are examined for subtotal generation. 

reset | running 

indicates the type of subtotal desired. If reset is selected, the subtotal counter is 
reset to 0 each time a subtotal is generated. If running is selected, the subtotal is 
not reset to 0. If a subtotal is requested on a column that is excluded, the 
subtotal is also excluded from the page. An exception to this rule is when all 
columns are excluded. Subtotals are provided in this case to allow reports 
consisting of some combination of counts, subcounts, totals, and subtotals only. 
(Default is reset) 

-total column_list, -tt column_list 

column_list determines what column totals to generate. (Default value for 
column_list is "", meaning no totals are generated for any columns.) 

column_list can be set to a list of column names or numbers. Totals are generated 
af ter the last detail line. If a total is requested on a column that is excluded, the total 
is also excluded from the page. An exception to this rule is when all columns are 
excluded. Totals are provided in this case to allow reports consisting of some 
combination of counts, subcounts, totals, and subtotals only. 



SPECIFIC COLUMN OPTIONS 

In the following descriptions, column_id means the column name, the number of 
the column in the query, or a star name which is used to match column names. 

-alignment column_id STR, -al columnjd STR 

column_id specifies which column the alignment applies to and STR is the 
alignment mode. STR can be set to center, left, right, both, or decimal N. The 
default value for STR depends upon the type of column selected. Character and bit 
strings default to left-alignment, decimal data with a non-zero scale defaults to 
decimal-point-alignment, and all other types default to right alignment. For 
decimal-point-alignment, the decimal alignment position within the display width 
is given a default value. This alignment position can be changed by specifying the 
value as "decimal N", where N is the character position within the display width 
where the decimal point is aligned. The alignment mode "both" specifies that the 
column value is aligned to the leftmost and rightmost character positions within its 
display width. Text is padded by insertion of uniformly distributed whitespace if 
necessary. 

-editing column_id STR, -ed columnjd STR 

STR specifies the additional editing to be done to the column value before it is 
placed on the page and colurnn_id specifies which column the editing applies to. 
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set f ormat options 



Multics active functions and subsystem active requests are normally used to provide 
additional editing. For example, the editing value: 

[e pic $S9>SS9v.SS [col umn_val ue salary]] 

places commas and dollar signs in the salary column. (Default value for STR is "", 
meaning additional editing is not done.) 

Refer to the column_value request for a description of usage. 

-folding column_id STR, -fold column_id STR 

STR determines what type of action occurs when a column value exceeds its display 
width and column_id specifies which column the folding applies to. STR set to 
truncate means that the value of the column is truncated to fit in the display width 
and the truncation character(s) are placed at the end of the value to indicate that 
truncation occurred. (Default value for STR is fill, meaning portions of the value 
which exceed the display width are moved down to the next line(s) until a correct fit 
is obtained.) 

-separator column_id STR, -sep column_id STR 

STR separates a column from the next one following it and column_id specifies 
which column the separator applies to. The last column on a line does not have a 
separator. STR can be any sequence of printable characters. (Def ault value f or STR 
is "<SP><SP>") 

-title column_id STR, -ttl column_id STR 

STR is the title placed above the column at the start of each page if the title_line 
option is set "on" and column_id specifies which column the title applies to. 
(Default value of STR is the name of the column. If the title is not the same number 
of characters as the display width of the column, the title is centered within the 
display width for its associated column. If the value of title is wider than the display 
width of the column, it is filled or truncated to obtain a correct fit, depending on 
the folding action of the parent column.) 

-width column_id N, -wid column_id N 

N determines the display width f or a column and column_id specifies which column 
the width applies to. N can be set to any positive integer. (Default value for N is the 
number of character positions needed to contain the value, after conversion from 
the subsystems data type, to character format.) 



can be chosen from the following: 
-brief, -bf 

specifies that the prompt string for values is not to be displayed. If the -brief and 
-long control arguments are both entered on the request line, the last one supplied is 
used. 



specifies that report writer set the value of the format option which immediately 
precedes this control argument to the system -supplied default. 



2. 



control_args 



-default 
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-long, -lg 

displays "Enter FORMAT_OPTION_NAME" prompt string for values when the 
-prompt control argument is provided. (Default) If the -brief and -long control 
arguments are both entered in the request line, the last one supplied is used. 

-no_reset, -nrs 

specifies that formatting options are not to be reset to system default values. 
(Default is that only user-specified options can be changed.) If the -reset and 
-no_reset control argument are both entered in the request line, the last one 
supplied is used. 

-prompt 

specifies that report writer prompts for the value of the format option which 
immediately precedes this control argument. A prompt string is written before the 
prompting action unless the -brief control argument is used. A line consisting of 
the single character "." terminates the prompted input mode. 

-reset, -rs 

specifies that all formatting options are to be reset to system default values before 
the values are changed for any other format options specified in the request line. If 
-reset and -no_reset are both entered in the request line, the last one supplied is 
used. 

-string STR, -str STR 

enters STR as a format option value when STR begins with a hyphen. 



NOTES 

At least one format option argument or the -reset control argument must be specified. 
Format option arguments and control arguments can be mixed freely in the request line, but a 
control argument cannot be placed between a format option name and a format option value. For 
example: 

sfo -page_width 80 -reset 

is a valid request, but 

sfo -page_width -reset 80 

is not valid. If a value is to be set that begins with a hyphen, the -string control argument must be 
given before the value, to distinguish it from control arguments and format option arguments. 



EXAMPLE 

sfo -width 1 25 

sfo -title emp_name "Employee Name" 

sfo -reset -page_width 80 -page_ 1 ength 60 

sfo -page_f ooter_val ue " ! ! - [d i spl ay_bu i 1 1 i ns page__number] - ! ! " 
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set f ormat options 



sfo -page_header_va 1 ue -prompt 
Enter page_heacier_va 1 ue . 

{[execute date]!SAMPLE REPORT! [execute time]! 

j M | 

!! — Page [d i spl ay_bui 1 t i ns page_number] — !! 

sfo -exclude exchange extension -width area_code 12 

sfo -editing area_code " [e f orma t_l i ne ^a/^a-^a [col umn_va 1 ue are3_code] 
[col umn_val ue exchange] [col umn_val ue extension]]" 
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SECTION 5 



REPORT WRITER SUBROUTINE DESCRIPTION 



This section contains the description of the report_writer_ subroutine and its functions, 
presented in alphabetic order. The description contains the name of the subroutine, discusses the 
purpose of the subroutine, lists the entry points, and describes the correct usage for each entry 
point. Notes are included for clarity. 
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convert and move row convert and move row 



Name: report writer 

The report_writer_ subroutine provides a programmer interface to the MRW system. 
Through it, application subsystems can include generalized report writing capabilities, with a 
minimal amount of coding required by the subsystem developer. The following entrypoints are 
provided: 

convert_and_move_row 

called to have a row value converted from differing data types and moved into the row 
value buffer. 

create_invocation 

called to create a report_writer_ invocation. 

define_columns 

called to inform report_writer_ that a set of columns are available for usage. 

destroy_invocation 

called to destroy a report_writer_ invocation. 

set_report_writer_inf o_ptr 

called to have the report_writer_ standard requests use the supplied report_writer_ info 
pointer (for subsystems that have more than one report_writer_ invocation present in 
the one subsystem (ssu_) invocation). 

set_table_manager 

called to have report_writer_ use the specified table manager procedure for this 
report_writer_ invocation. 



Entry: convert and move row 

This entry converts a row of differing data types to a row of character string values and 
places it in the row value buffer. 



USAGE 

declare repor t_wr i ter_$conver t_and_move_row entry (ptr, (*) ptr) ; 
ca 1 1 repor t_wr i ter_$conver t_and_move_row (repor t_wr i ter_i nf o_ptr , 
value_ptrs) ; 



ARGUMENTS 

report_writer_inf o_ptr 

is the pointer to the report_writer_ info structure returned by the create_in vocation 
entrypoint. (Input) 

value_ptrs 

is an array of pointers that point to the individual column values that are to be 
converted. (Input) 
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NOTES 

The number of pointers in the array must be equivalent to the number of columns defined in 
the table. Refer to "Data Conversions" in Section 3 for a code fragment which shows the usage of 
this subroutine. 



Entry: create invocation 

This entry creates a report_writer_ invocation. It adds the standard report_writer_ request 
table and the standard requests info segments directory at location 99999 (see Notes). 



USAGE 

declare repor t_wr i ter_$create_i nvocat i on entry (char (*) , ptr, ptr, 

fixed bin(35)» char (*) varying); 
call report_wr i ter_$create_i nvocat i on (tabl e_manager_name, 
sci_ptr, repor t_wr i ter_ptr , code, message); 



ARGUMENTS 

table_manager_name 

is the name of the table manager procedure f or the application subsystem that is creating 
the report writer invocation. If the name is blank, report_writer_ obtains the name of 
the application subsystem via the ssu_$get_subsystem_name subroutine and uses this as 
the table manager procedure name. Entry variables are constructed by report_writer_ 
using the name of the table manager procedure. (Input) 

sci_ptr 

is the ssu_ info pointer returned to the application subsystem when the ssu_ invocation is 
created. If this parameter is null, the report_writer_ invocation is not created. (Input) 

report_writer_info_ptr 

is the pointer to the report_writer_ info structure. This pointer is passed as the first 
parameter to every other report_writer_ entry. (Output) 

code 

is a standard error code. If this is non-zero the invocation could not be created. 
(Output) 

message 

if code is non-zero, this parameter contains the reason why the invocation could not be 
created. Declaring this argument as "character(128) varying" provides an area large 
enough to contain any returned error message. (Output) 



NOTES 

The table manager procedure is a program supplied by the application subsystem to manage 
data retrieval from its source data file. The report_writer_ creates entry variables of the form 
"table_manager_name$XX", where XX are the entries that must be available in the table manager 
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procedure. The required entries are create_table, delete_table, and get_row. The optional entry 
is get_query. See "Subsystem Table Manager Procedure" in Section 3 for additional information. 

The report_writer_ request tables provide a mechanism to include all of the report_writer_ 
standard requests (the default when an invocation is created), or selected individual 
report_writer_ requests. The request table "report_writer_request_table_$standard_requests" is 
used by the report_writer_$create_invocation entrypoint in a call to ssu_$add_request_table to 
add the report_writer_ standard requests to the subsystem's set of requests. If the standard 
requests are not required, the subsystem should call ssu_$delete_request table with this as a 
parameter, after the call to report_writer_$create_in vocation. The report_writer_ standard 
requests are: column_value, display, display_builtins, list_format_options, 
restore_format_options, save_format_options, and set_format_options. The other request 
tables defined to allow the addition of single requests are 
report_writer_request_table_$XXX_request, where XXX is the short name of the request. These 
can be chosen from: civ, di, dib, lsfo, rsfo, sfo, and svfo. 

The report_writer_inf o_dirs_ data segment provides a mechanism to include the directory 
containing the info segment for a request. The report_writer_info_dirs_$standard_requests is 
used by the report_writer_$create_in vocation entrypoint in a call to ssu_$add_info_dir, to add 
the inf o directory containing the inf o segments f or the standard requests. If the standard requests 
are not required, the subsystem should call ssu_$delete_info_dir with this as a parameter, after 
the call to report_writer_$create_invocation- The other data items defined to allow the addition 
of directories which contain the info segment for a single request are 
report_writer_info_dirs_$XXX_requests, where XXX is the short name of the request. These 
can be chosen from: civ, di, dib, lsfo, rsfo, sfo, and svfo. 



Entry: define__columns 

This entry is used to inform report_writer_ that a set of columns have been selected. All 
specific and general column options have new values assigned based on the newly selected 
columns. 



USAGE 

declare report_wr i ter_$def i ne_col umns entry (ptr, ptr, 

fixed bin (35), char (*) varying); 
call report_wr i ter_$def i ne_col umns (repor t_wr i ter_i nf o_ptr , 
row_i nf o_ptr , code, message); 



ARGUMENTS 

report_writer_inf o_ptr 

is the pointer to the report_writer_ info structure returned by the create_in vocation 
entrypoint. (Input) 

row_info_ptr 

is a pointer to the row_info structure described in the include file rw_row_info.incl.pll 
(See "Notes" below.) If this pointer is null, any previously defined specific and general 
column option values are deleted, and the only operations allowed are to general report 
options until this entry is called again with a valid row_info pointer. (Input) 
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define__columns 



code 

is a standard error code. If this code is non-zero the values of any previously defined 
specific and general columns options will remain unchanged. (Output) 

message 

if code is non-zero this parameter will contain the reason for the failure. Declaring this 
argument as "character (128) varying" provides an area large enough to contain any 
returned error message. (Output) 



NOTES 

The row_info structure declared in the include file rw_row_info.incl.pll is listed below, 
followed by a description of the members of this structure. 

declare 1 row_info aligned based ( row_i nf o_ptr ) , 
2 version char(8) unaligned, 
2 value_ptr ptr, 
2 val ue_l ength fixed bin(21), 
2 number_of _col umns fixed bin, 
2 current_col umn_number fixed bin, 
2 column ( row_i nf o_i ni t_number_of _col umns 

refer ( row_i nf o . number_of_col umns ) ) , 

3 names char (128) varying, 

3 descriptors bit(36), 

3 lengths fixed bin(21), 

3 indexes fixed bin(2l); 

where: 
version 

specifies to report_writer_ that the application subsystem is using a particular version of the 
structure. The only version currently supported by report_writer_ is version 1. The value of 
ROW_INFO_VERSION_l, declared in the same include file, should be assigned to 
row_info. version by the subsystem. (Input) 

vaiue_ptr 

is filled in by report_writer_ and points to the buffer where the row value is placed by the 
application subsystem's table manager procedure or the 
report_writer_$convert_and_move_row entrypoint See "The Row Value Buffer" in Section 
3 for additional information. (Output) 

value_length 

is filled in by report_writer_ and is the length of the buffer for the row value. This is set to 
the exact number of characters needed to contain the row value after conversion from 
internal data types to the non-varying, unaligned character data types report_writer_ uses. 

number_of_columns 

is filled in when the application subsystem allocates the row_info structure, by setting the 
variable row_info_init_number_of_columns to the number of columns that should be 
present in the table, before the allocate statement is executed. (Input) 

current_column_number 

is set to zero by report_writer_ and can be used by the application subsystem's table manager 
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define columns 



procedure to place individual column values into the row value buffer. See "The Row Value 
Buffer" in Section 3 for additional information. (Output) 

names 

are filled in by the application subsystem, and are the names of the individual columns. 
These names must not contain whitespace because of the request line syntax of the 
report_writer_ standard requests. (Input) 

descriptors 

are filled in by the application subsystem. They are standard data type descriptors for the 
column data as it appears in the source file that the subsystem's table manager retrieves from. 
In many cases they describe columns that are not nonvarying, unaligned character data types, 
and report_writer_ must convert the column values to nonvarying character strings. It uses 
these data descriptors to do data conversion. See "Data Conversions" in Section 3 for 
additional information. It also uses these descriptors when generating default report column 
widths, column alignment modes, etc. 

If a descriptor is completely zero, the column is assumed by report_writer_ to be a 
nonvarying, unaligned character string. In this case, the lengths field is used to determine the 
length in characters of the column. The descriptor is then set by report_writer_ to a 
nonvarying, unaligned character descriptor and its size portion is set to the value found in the 
lengths field. 

Refer to the Programmer's Reference Manual, for a description of Multics standard data 
type descriptors. Refer to the include files "arg_descriptor.incl.pll" and 
"std_descriptor_types.incl.pH" for structures and named constants to set descriptors. 
(Input /Output) 

lengths 

are filled in by report_writer_, and each is the number of characters needed to contain the 
column value after conversion from any supported data type to nonvarying, unaligned 
character format In the case where the descriptor is completely zero, lengths are set by the 
caller. The report_writer_ examines the value of this field to determine the length in 
characters for the column. See "The Row Value Buffer" in Section 3 for additional 
information. (Input/ Output) 

indexes 

are filled in by report_writer_, and each is the index into the row value buffer for a 
particular column. See "The Row Value Buffer" in Section 3 for additional information. 
(Input) 

There are also three variables defined in this include file to provide a convenient method to 
access the row_vaiue buffer. A description of these variables follow. 

row_value variable 

provides a method to refer to the complete row value. Its declaration is: 

declare row_yalue char (row_i nfo.value_length) 
based (row_i nf o.val ue_ptr) ; 

A PL/ 1 program to set the row value completely blank could use the PL/ 1 statement: 
row_value = 11 11 ; 

row_value_as_an_array variable 

provides a method to refer to any single character within the row value. Its declaration 
is: 
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report writer. 

set report writer inf o ptr 



declare row value as an array (row info. value length) 
char(l) based (row_i nf o. va 1 ue_ptr) ; 

A PL /I program to set the 15th character within the row_value to a blank could use the 
PL/ 1 statement: 

row_value_as_an_array (15) = " 

column_value variable 

provides a method to refer to a complete column value. Its declaration is: 

declare col umn_val ue 

char (row_info. column. lengths 

(row_i nf o.current_col umn_number) ) 
based (addr (row_va 1 ue_as_an_ar ray 
(row_i nfo.col umn. i ndexes 

(row_i nf o.current_col umn_number) ) ) ) ; 

A PL/I program to set all of the columns to blanks could use the PL/I code fragment: 

do row_i nf o. current_col umn_number = 1 to row_i nf o . number_of_col umns ; 
column_value = " 11 ; 

end; 



Entry: destroy invocation 

This entry destroys a report_writer_ invocation. 

USAGE 

declare report_wr i ter_$destroy_i nvocat ion entry (ptr); 

call report_wr i ter_$destroy_i nvocat i on (report_wr i ter_i nf o_ptr) ; 



ARGUMENTS 

report_writer_inf o_ptr 

is the pointer to the report_writer_ info structure. If this pointer is null, the call is 
ignored. This pointer is set to null after the invocation is destroyed. (Input/Output) 



Entry: set_report__writer_inf o„ptr 

This entry is used by complex subsystems that require more than one report_writer_ 
invocation to be present in the subsystem invocation. It takes the caller provided report_writer_ 
info pointer and places it in an internal location associated with the sci_ptr. When the next 
report_writer_ standard request is invoked, it uses the new report_writer_ info pointer now 
associated with its sci_ptr parameter. 
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set table manager 



USAGE 

declare repor t_wr i ter_$set_repor t_wr i ter_i nf o_ptr entry (ptr, ptr, 

fixed bin(35)» char (*) varying); 
cal 1 report_wr i ter_$set_repor t_wr i ter_i nf o_ptr 

(repor t_wr i ter_i nfo_ptr , sci_ptr, code, message); 



ARGUMENTS 

report_writer_inf o_ptr 

is the pointer to a report_writer_ info structure. This pointer becomes the 
report_writer_ info pointer that is passed to the report_writer_ standard requests. 
(Input) 

sci_ptr 

is the pointer to the ssu_ info structure returned to the subsystem by the 
ssu_$create_invocation entrypoint. (Input) 

code 

is a standard error code. If this code is non-zero, the current report_writer_ info 
pointer remains in effect. (Output) 

message 

if code is non-zero this parameter contains the reason for the failure. Declaring this 
argument as "character (128) varying" provides an area large enough to contain any 
returned error message (Output) 



NOTES 

The most common type of subsystem using repor t_writer_ is one where there is only one 
report_writer_ invocation present in the one subsystem invocation. If a subsystem requires more 
than one report_writer_ invocation to be present in the one subsystem invocation, call the 
report_writer_$create_in vocation as many times as required, saving the returned report_writer_ 
info pointer after each call. This entrypoint is then called with the desired report_writer_ info 
pointer before any of the report_writer_ standard requests are used. The call to this entrypoint 
ensures that the correct report_writer_ info pointer is used by the report_writer_ standard 
requests. 



Entry: set table manager 

This entry is used by complex subsystems that require more than one table_manager 
procedure to be used in a report_writer_ invocation. It takes the caller provided table_manager 
name and creates entry variables to the expected entrypoints. (See the 
"report_writer_$create_in vocation entrypoint" for more information on the table_manager 
procedure.) After this entrypoint is called, the next invocation of the report_writer_ display 
request uses this new table_manager procedure. 
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declare repor t_wr i ter_$set_tab 1 e_manager entry (ptr, char (*) , 

fixed bin (35) 5 char (*) varying): 
cal 1 report_wr i ter_$set_tab 1 e_manager 

(repor t_wr i ter_i nfo_ptr , tabl e_jnanager_name, code, message); 



ARGUMENTS 

report_writer_inf o_ptr 

is the pointer to the report_writer_ info structure returned by the 
report_writer_$create_invocation entrypoint. (Input) 

table_manager_name 

is the name of the new table_manager procedure. (Input) 

code 

is a standard error code. If this code is non-zero, the current subsystem table_manager 
procedure remains in effect. (Output) 

message 

if code is non-zero, this parameter contains the reason for the failure. Declaring this 
argument as "character (128) varying" provides an area large enough to contain any 
returned error message. (Output) 



NOTES 

The most common type of subsystem using report_writer_ is one where there is only one 
table_manager procedure required for the one report_writer_ invocation. If a subsystem wishes 
to switch between different tabie_manager procedures within one report_writer_ invocation, 
this entrypoint should be called with the name of the new table_manager procedure. The call to 
this entrypoint results in the new table_manager procedure being called the next time the 
report_writer_ display request is used. 
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TABLE MANAGER SUBROUTINE DESCRIPTION 



The table_manager procedure is written by the application programmer, and is part of the 
application that uses report_writer_. The table_manager procedure is responsible f or retrieving 
rows from the source data file (or files) that the application wishes to use in formatting the 
report. 

At specific times during the retrieval operation, report_writer_ calls the table_manager 
procedure to accomplish certain tasks. At the beginning of the retrieval, report_writer_ calls the 
create_table entrypoint of the table_manager procedure to prepare for data retrieval and to 
retrieve the first data row. Each time another row is needed during the formatting operation, 
report_writer_ calls the get_row entrypoint of the table_manager procedure. After the retrieval 
is complete, report_writer_ calls the delete_table entrypoint of the table_manager procedure. 
These three entrypoints must be present in the table_manager procedure, or the 
report_writer_$create_in vocation entrypoint refuses to create a report_writer_ invocation. 

There is an optional entrypoint in the table_manager procedure which can be provided by 
applications that support user selected data retrieval. An example of this type of application is 
the LINUS subsystem. LINUS provides a query statement that allows users to choose the data of 
interest to them. When the report_writer_ save_format_options request is invoked with the 
-query control argument, report_writer_ tries to find this optional entrypoint in the applications 
table_manager procedure. If this entrypoint is not present, report_writer_ prints an error 
message stating that the operation is not supported. If the entrypoint is present, report_writer_ 
. calls it to obtain the requests which the user typed to select the data currently being retrieved. 
These requests are saved, along with the report layout, in an exec_com segment, A subsequent 
restore_format_option request identifying the exec_com causes these requests to be executed. 
The execution of these requests results in the same data being selected and the same format 
options set, so that the report can be produced at a later time. 

The following paragraphs describe the table_manager procedure entrypoints. Detail is 
provided on how the report_writer_ declares the entrypoints, and how the report_writer_ calls 
the entrypoints. The parameters passed to these entrypoints by report_writer_ are also explained. 
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Entry: table managerScreate table 

This entry is called by report_writer_ when the display request is invoked with the 
-new_retrieval control argument (Default). It performs any initialization required to perform 
its data retrieval function. It then retrieves the first row from its source data file, and places it in 
the row_value buffer. 



USAGE 

declare tabl e_manager$create_table entry (ptr, fixed bin (35)); 
call tabl e_manager$create_tabl e (info_ptr, code); 



ARGUMENTS 
info_ptr 

is the pointer to the application's info structure that is passed to the 
ssu_$create_invocation entrypoint by the application when the ssu_ invocation is 
created. (Input) 

code 

is a standard Multics error code. If this entry finds the source data file empty when the 
retrieval of the first row is attempted, it sets this code to rw_error„$no_data. If this 
entry executes successf ully it sets this code to zero. If this entry encounters any other 
problem during execution, it sets the code to indicate what the source of the problem is. 
(Output) 



NOTES 

The application's info structure must contain the row_info_ptr passed to 
report_writer_$define_columns. This points to the row_info structure, which in turn points to 
row_value buffer. table_manager$create_table must move the first row of data into this 
row_value buffer, either by a PL/ 1 assignment or substr pseudovariable, or by calling 
report_writer_$convert_and_move_row. 



Entry: table managerSdelete table 

This entry is called by report_writer_ when the formatting of the report is completed. After 
the last data row is retrieved, it performs any termination steps required by the application. 



USAGE 

declare table_manager$delete_table entry (ptr, fixed bin (35)) » 
call tabl e_manager$del ete_tabl e (info__ptr, code); 



ARGUMENTS 
info_ptr 

is the pointer to the application's info structure that is passed to the 



6-2 



GB63-00 



table manager$delete table 



table manager$get query 



ssu_$create_invocation entrypoint by the application when the ssu_ invocation is 
created. (Input) 

code 

is a standard Multics error code. If this entry executes successfully it sets this code to 
zero. If this entry encounters any problem during execution, it sets the code to indicate 
what the source of the problem is. (Output) 



Entry: table manager$get query 

This entry is called by report_writer_ when the save_format_options request is invoked with 
the -query control argument. It returns to report_writer_ the requests needed to select the data 
currently being displayed, so that these requests can be saved along with the report layout. If the 
application does not support user requests to select data, this entrypoint should not be provided. 



USAGE 

declare tab 1 e_manager$get_query entry (ptr, ptr, 

fixed bin (21), fixed bin (35)); 
call tabl e_manager$get_query (info_ptr, query_segment_ptr , 

query_l ength, code) ; 



ARGUMENTS 
info_ptr 

is the pointer to the application's info structure that is passed to the 
ssu_$create_invocation entrypoint by the application when the ssu_ invocation is 
created. (Input) 

query _segment_ptr 

is the pointer to a segment provided by report_writer_, where the data selection requests 
are placed by this entrypoint. (Input) 

query_length 

is the length in characters of the returned data selection requests. This entrypoint sets 
the length to let report_writer_ know how many characters are being returned. (Output) 

code 

is a standard Multics error code. If this entry executes successfully it sets this code to 
zero. If this entry encounters any problem during execution, it sets the code to indicate 
what the source of the problem is. (Output) 



NOTES 

The data selection requests are dependent on the application, and should contain whatever 
requests are necessary to select the data currently being displayed. These requests are executed 
from within a subsystem exec_com when the saved report layout is restored by the report_writer_ 
restore_format_options request. An example of data selection statments specific to the LINUS 
subsystem follows. 
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table manager$get query 



table__manager$get_ row 



input_query -force -brief -termi nal_i nput 
select * from employee 

trans 1 ate_query 

If any ampersands are found within the data selection requests that would be interpreted by 
exec_com when the report layout is restored, they are protected by save_format_options with 
double ampersands before being placed in the saved report layout file. In the case of a subsystem 
like LINUS, a portion of a select statement that looked like: 

& name - "Smith" 

would be saved as: 

&& name = "Smi th" 



Entry: table_manager$get row 

This entry is called by report_writer_ when a row is needed during the formatting of the 
report. It retrieves a row from its source data file and places it in the report_writer_ row value 
buffer. 



USAGE 

declare tab 1 e_manager $get_row entry (ptr, fixed bin (35)); 
call tabl e_manager$get_row (info_ptr, code); 



ARGUMENTS 
info_ptr 

is the pointer to the application's info structure that is passed to the 
ssu_$create_invocation entrypoint by the application when the ssu_ invocation is 
created. (Input) 

code 

is a standard Multics error code. If this entry executes successfully it sets this code to 
zero. If this entry encounters an end-of-f ile on the source data file, it sets this code to 
error_table_$end_of_info. If this entry encounters any other problem during 
execution, it sets the code to indicate what the source of the problem is. (Output) 



NOTES 

The application's info structure must contain the row_info_ptr passed to 
report_writer_$define_columns. This points to the row_info structure, which in turn points to 
row_value buffer. table_manager$get_row must move the first row of data into this row_value 
buffer, either by a PL/ 1 assignment or substr pseudo variable, or by calling 
report_writer_$convert_and_move_row. 
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SECTION 7 



DISPLAY EMPLOYEE PL/1 EXAMPLE 



The sample user session in Section 2 was done using the PL/ 1 program shown on the 
following pages. This PL /I program uses the report_writer_ and ssu_ subroutines to construct an 
application subsystem that includes the standard ssu_ and report_writer_ requests. Line numbers 
are included in the program listings for purposes of commentary. 



MAIN PROCEDURE 

1 display_employee: proc; 



2 cal 1 initial ize; 

3 on cleanup call destroy_i nvocat i on ; 

4 message = create_i nvocat ion (code); 

5 if code ~= 0 

6 then call com_err_ (code, "di spl ay_empl oyee " , message); 

7 else call ssu_$listen (sci_ptr, null, (0)); 

8 call destroy_i nvocat i on; 

9 return; 



lines 1-9 

This is the main procedure that is invoked when a user at the terminal types 
display .employee. Line 2 calls an internal procedure to initialize the state of the 
program. Line 3 establishes a cleanup handler that calls destroy_invocation if the 
cleanup condition is signalled. Line 4 creates the display .employee invocation. Lines 5 
and 6 check the error code and display the code and message if non-zero. Line 7 reads 
request lines from the terminal if the code is zero. Line 8 destroys the display .employee 
invocation. 
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TABLE MANAGER 



create table entry 

10 create_tabl e : entry ( 

11 based_i nf o_ptr_parm , /* input: points to based_info structure */ 

12 code_parm); /* output: success or failure */ 

13 based_i nf o_ptr - based_i nf o_ptr_parm ; 

14 call dsl_$retr ieve (based_i nf o . data_base_i ndex , 

15 "-range (e employee) -select e", based_empl oyee , code_parm); 

16 if code_parm = 0 

17 then call report_wr i ter_$convert_and_move_row ( 

18 based_inf o. report_wr i ter_i nf o_ptr , based_i nf o . val ue_ptrs ) ; 

19 else if code_parm = mrds_error_$tupl e_not_f ound 

20 then code_parm = rw_error_$no_data ; 

21 return; 

delete table entry 

22 del ete_tabl e : entry ( 

23 based_i nf o_ptr_parm, /* input: points to based_info structure */ 

24 code_parm); /* output: success or failure */ 

25 code_parm = 0; 

26 return; 

get row entry 

27 get_row: entry ( 

28 based_i nf o_ptr_parm, /* input: points to based_info structure */ 

29 code_parm); /* output: success or failure */ 

30 based_i nf o_ptr = based_i nf o_ptr_parm ; 

31 call dsl_$retr ieve (based_info.data_base_index, 

32 "-another", based_empl oyee, code_parm) ; 

33 if code_parm = 0 

34 then call report_wr i ter_$convert_and_move_row ( 

35 based_info. report_wri ter_info_ptr , based_i nf o . val ue_ptrs ) ; 

36 else if code_parm = mrds_error_$tupl e_not_f ound 

37 then code_parm = error_table_$end_of_inf o; 

38 return; 
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lines 10-38 

These are the table manager entries called by report_writer_ to start and stop the data 
retrieval, and to get rows. When they are called they are given a new stack frame, so they 
use the based_info structure to access the first stack frame's automatic variables. Lines 
10 to 21 create a new table, and are called when the report_writer_ display request's 
-new_retrieval control argument is used. Line 14 retrieves the first tuple from dsl_, and 
line 17 calls a report_writer_ entry to convert the row to characters and move it into the 
row_value buf f er, if the retrieval was successf ul. If not successf ul, lines 19 and 20 return 
rw_error_$no_data if the relation was empty, or the dsl_ error code if it was anything 
else. 

lines 22-26 

This is the entrypoint called by report_writer_ after the completion of the report. It 
does not have any operations to perform, so it just sets the code to zero and returns. 

lines 27-38 

This is the entrypoint called by report_writer_ to retrieve a row of data from the source 
file and move it into the row value buffer. It retrieves the tuple from dsl_, and calls a 
report_writer_ entry to convert the row and move it into the row value buffer if the 
error code is zero. If the code is non-zero it replaces the mrds_error_$tuple_not_f ound 
code with error_table_$end_of_info, and returns any other dsl_ error code back to 
report_writer_. 
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INTERNAL PROCEDURES 



create invocation 

39 create_i invocation: proc ( 



40 code_parm) /* output: success or failure */ 

41 returns (char (256) varying); /* output: reason for the failure */ 

42 declare ci_loop fixed bin; 

43 declare ci_message char (256) varying; 

44 declare code_parm fixed bin (35) parm; 

45 code_parm = 0; 

46 call dsl_$open ( "empl oyee_data_base" , 

47 info.data_base_index, EXCLUSI VE_RETRI EVE , code_parm); 

48 if code_parm "= 0 

49 then return ("Unable to open empl oyee_data_base . " ) ; 

50 call dsl_$get_attribute_l ist ( i nf o . data_base_i ndex , "employee", 

51 work_area_ptr , mrds_attr ibute_l ist_structure_version, 

52 mrds_attr i bute_l i st_ptr , code_parm); 

53 if code_parm ~ = 0 

54 then return ("Unable to get the list of attributes for employee."); 

55 call ssu_$create_i nvocat i on ( "di spl ay_empl oyee " , "1.0", 

56 based_i nf o_ptr , null, "", sci_ptr, code_parm); 

57 if code_parm ~ = 0 

58 then return ("Unable to create the ssu_ invocation."); 

59 call report_writer_$create_i nvocat ion ("", sci_ptr, 

60 i nf o . report_wr i ter_i nf o_ptr , code_parm, ci_message); 

61 if code_parm ~= 0 

62 then return ( c i_message ) ; 

63 call ssu_$add_request_table (sci_ptr, 

64 addr (ssu_request_tables_$standard_requests) , 100000, code_parm); 

65 if code_parm ~ = 0 

66 then return ("Unable to add the ssu_ standard requests."); 

67 call ssu_$add_i nf o_di r (sci_ptr, ssu_i nfo_di rector i es_$standard_requests , 

68 100000, code_parm); 

69 i f code_parm n = 0 

70 then return ("Unable to add the ssu_ info directories."); 

71 row_info_ini t_number_of _col umns = mrds_attr ibute_l ist . num_attrs_in_view; 

72 allocate row_info in (work_area) set ( row_i nf o_ptr ) ; 

73 row_info. version = R0W_INF0_VERSI0N_1 ; 

74 do ci_loop = 1 to row_info_init_number_of_columns; 

75 row_i nf o . col umn ( c i_l oop) . names 

76 = rtrim (mrds_attribute_l ist .attribute ( c i_l oop ). model _name ) ; 

77 row_i nf o . col umn ( ci_l oop) . descr i ptors 
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78 = mrds_attr ibute_l ist .attribute (ci_l oop) . user_data_type ; 

79 end; 

80 call report_wr i ter_$def i ne_eol urnns ( i nf o . report_wr i ter_i nf c_ptr , 

81 row_i nf o_ptr , code_parm, c i_message ) ; 

82 if code_parm ~ = 0 

83 then return (ci_message) ; 

84 i nf o . empl oyee_ptr = addr (employee); 

85 i nf o . val ue_ptrs (1) = addr (employee . name) ; 

86 i nf o . val ue_ptrs (2) = addr (empl oyee . j ob ) ; 

87 i nf o . val ue_ptrs (3) = addr (employee . salary) ; 

88 i nf o . val ue_ptrs (4) = addr (empl oyee . age ) ; 

89 i nf o . va 1 ue_ptrs (5) - addr ( empl oyee . sex ) ; 

90 info. value_ptrs (6) = addr (employee . f ami ly) ; 

91 i nf o . val ue_ptrs (7) = addr (empl oyee . state) ; 

92 inf o.value_ptrs (8) = addr (empl oyee . ci ty) ; 

93 return ( " " ) ; 

94 end create_i nvocat i on ; 



lines 39-90 

This is the internal procedure that creates a display _employee invocation. Lines 46 to 49 
open the data base that is expected to be in the user's working directory, and pass back an 
error message and code if the data base cannot be opened. Lines 50 to 54 have dsl_ fill in 
the mrds_attribute_list structure, and pass back an error message and code if the 
attribute list cannot be obtained. Lines 55 to 58 create an ssu_ invocation and pass back 
an error message and code if there is a failure. Lines 59 to 62 create a report_writer_ 
invocation, and pass back an error message and code if there is a failure. Lines 63 to 70 
add the standard ssu_ requests and info directory. Lines 71 to 79 allocate the row_info 
structure and fill in the version number, and names and descriptors arrays. Lines 80 to 
83 call a report_writer_ entry to inform it that a set of columns have been selected, 
passing back an error message and code if there is a failure. Lines 84 to 92 fill in the 
value_ptrs array to locations in the employee structure that dsl_ retrieves the row into. 
This is necessary so that the create_table and get_row entrypoints reference the 
automatic employee structure in the main procedures stack frame. Line 93 returns a 
zero length error message indicating a normal execution. 
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destroy invocation 

95 destroy_i nvocat i on : proc; 

96 declare di_code fixed bin (35); 



97 if i nf o . data_base_i ndex ~= 0 

98 then call dsl_$close ( i nf o . data_base_i ndex , di_code); 

99 call report_wr i ter_$destroy_i nvocat i on ( i nf o . report_wr i ter_i nf o_ptr ) ; 

100 if mrds_attr ibute_l i st_ptr " = null 

101 then free mrds_attr i bute_l i st in (work_area); 

102 if row_info_ptr " = null 

103 then free row_info in (work_area); 

104 call ssu_$destroy_i nvocat ion (sci_ptr); 

105 return; 

106 end destroy_i nvocat i on ; 



lines 95-106 

This is the procedure called to destroy a display _employee invocation. It closes the data 
base if open, destroys the report_writer_ invocation, frees the mrds_attribute_list 
structure if it was allocated, frees the row_inf o structure if it was allocated, and destroys 
the ssu_ invocation. 
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initialize 

107 initialize: proc; 



108 based_i nf o_ptr = addr (info); 

109 i nf o . data_base_i ndex = 0; 

110 i nf o . report_wr i ter_i nf o_ptr = null; 

111 i nf o . val ue_ptrs (*) = null; 

1 12 sci_ptr = nul 1 ; 

113 mrds_attr ibute_l ist_ptr = null; 

114 row_info_ptr ~ null; 

115 work_area_ptr = get_system_f ree_area_ (); 

116 return; 



1 17 end initial ize; 



lines 107-117 

This is the procedure called to initialize for a display .employee invocation. It sets the 
info pointer to point to its own info structure; sets other pointers and the data base index 
to initial values so the destroy_invocation entrypoint can execute correctly; and sets the 
work_area_ptr to the area used for allocations. 
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DECLARATIONS 



118 declare EXCLUSI VE_RETRI EVE fixed bin(35) 

internal static options (constant) init(3); 

119 declare addr builtin; 

120 declare 1 based_empl oyee like employee based (based_i nf o . empl oyee_ptr ) ; 

121 declare 1 based_info like info based (based_i nf o_ptr ) ; 

122 declare based_i nf o_ptr ptr; 

123 declare based_i nf o_ptr_parm ptr parm; 

124 declare cleanup condition; 

125 declare code fixed bin(35); 

126 declare code_parm fixed bin(35) parm; 

127 declare com_err_ entry( ) opt i ons( variabl e ) ; 

128 declare dsl_$close entry( ) opt i ons ( var iabl e ) ; 

129 declare dsl_$get_attribute_l ist entry (fixed bin(35), 

char(*), ptr, fixed bin, ptr, fixed bin(35)); 

130 declare dsl_$open entry() opt i ons ( var i abl e ) ; 

131 declare dsl_$retrieve entry( ) opt i ons( var i abl e ) ; 

132 declare 1 employee aligned, 

133 2 name char(10) unaligned, 

134 2 job fixed decimal (2,0) unaligned, 

135 2 salary fixed decimal (7,2) unaligned, 

136 2 age fixed decimal ( 2, O) unaligned, 

137 2 sex char( 1 ) unaligned, 

138 2 family char(1) unaligned, 

139 2 state char(2) unaligned, 

140 2 city char(13) unaligned; 

141 declare error_tabl e_$end_of _i nf o fixed bin(35) ext static; 

142 declare get_system_f ree_area_ entry( ) returns ( ptr ) ; 

143 declare 1 info aligned, 

144 2 data_base_i ndex fixed bin(35), 

145 2 report_wr i ter_i nf o_ptr ptr, 

146 2 employee_ptr ptr, 

147 2 value_ptrs(8) ptr; 

148 declare message char(256) varying; 

149 declare mrds_error_$tupl e_not_f ound fixed bin(35) ext static; 

150 declare null builtin; 

151 declare report_wr i ter_$convert_and_move_row entry (ptr, (*) ptr); 

152 declare report_wr i ter_$create_i nvocat i on entry (char(*). 

ptr, ptr, fixed bin(35), char(*) varying); 

153 declare report_wr i ter_$def i ne_col umns entry (ptr, ptr, 

fixed bin(35), char(*) varying); 

154 declare report_wr i ter_$destroy_i nvocat ion entry (ptr); 

155 declare rtrim builtin; 

156 declare rw_error_$no_data fixed bin(35) ext static; 

157 declare ssu_info_di rector ies_$standard_requests char(168) external; 

158 declare sci_ptr ptr; 

159 declare ssu_$add_i nf o_di r entry (ptr, char(*), fixed bin, fixed bin(35)); 

160 declare ssu_$add_request_tabl e entry (ptr, ptr, fixed bin, fixed bin(35)); 

161 declare ssu_$create_i nvocat i on entry (char(*), char(*), 

ptr, ptr, char(*), ptr, fixed bin(35)); 

162 declare ssu_$destroy_i nvocat i on entry (ptr); 

163 declare ssu_$listen entry (ptr, ptr, fixed bin(35)); 
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164 declare ssu_request__tabl es_$standard_requests bit(36) aligned external; 

165 declare sys_i nf o$max_seg_s i ze fixed bin(35) ext static; 

166 declare work_area area ( sys_i nf o$max_seg_s i ze ) based ( work_area_ptr ) ; 

167 declare work_area_ptr ptr; 

168 %include mrds_attr ibute_l i st ; 



169 %include rw_row_i nf o ; 

170 end d i spl ay_empl oyee ; 



lines 118-170 

These are the declarations for the display .employee procedure. 
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Even though the columns are re-ordered (line 4 above), the user must still set and list them in the 
selected order sequence. For example: 



69 ! di spl ay_empl oyee : sfo -wid 8 -def aul t ; 1 sf o -wid 8 
-width city "13" 



Although city appears on the page first (i.e., left column in above example), the column is still 
column 8. 



71 ! di spl ay_empl oyee : sfo -co 7 8;lsfo -co 

72 -col umn_order "state city name job salary age sex family" 



Notice that all columns were not named in the -column_order request above (line 71) and that the 
system defaults all names (line 72). Future displays of the report will have the columns reordered 
to 78123456 until changed by the user. 
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